open-galapagos 0.3.0

A user-friendly, open-source platform for LLM-driven evolutionary search on scientific-discovery tasks.

Galapagos 🐢

LLM-driven evolutionary search. One loop. Swappable slots.

Docs · Quickstart · Concepts · The Hub · Examples

---

Any LLM × 8 scaffolds × 230+ tasks. One component vocabulary. One leaderboard.

Galapagos is a user-friendly, open-source platform for LLM-driven evolutionary search on scientific-discovery and optimization tasks. Load an evolutionary-search scaffold and an evaluation task in a few lines, point them at any LLM, and let the loop evolve solutions that maximize a metric — circle packings, function minimizers, GPU kernels, algorithms, prompts, and more.

import galapagos as gx

model    = gx.GalapagosModel.from_card(name="openai/gpt-5.5", host="openrouter")  # or name="mock" (offline)
scaffold = gx.GalapagosScaffold.from_card(name="openevolve", model=model)
task     = gx.GalapagosTask.from_card(name="circle_packing")
result   = scaffold.run(task=task)

print(result.best_score, result.summary)

That's the whole loop: pick a method, pick a task, point at a model, run.

name="mock" swaps in a zero-cost offline model that still performs real perturbations — a run improves with no API key and no setup.

Cards: the protocol

After AlphaEvolve, LLM-evolution methods exploded — OpenEvolve, ShinkaEvolve, GEPA, AdaEvolve, EvoX, Meta-Harness, and more. Each is structurally the same loop (select → prompt → propose → evaluate → repeat), but each shipped as an incompatible codebase with a bespoke harness, so published numbers were never apples-to-apples. Galapagos unifies them behind one component vocabulary and one leaderboard. (Why Galapagos.)

What makes that work is the card: a versioned YAML, modeled on the model & dataset cards of the Hugging Face Hub. A card is the single source of truth shared by the local library and the live Hub — the same YAML loads a method on your laptop and lists it in the registry. There are four kinds:

Card kind	Describes	Publish it to…
Scaffold card	an evolutionary-search method (its six components)	share your method
Task card	an evaluation task + its scorer	share your benchmark
Model card	an LLM backend + host	share a model config
Verification card	a discovery — best solution + trajectory	submit a result

Learn the protocol in Concepts › Cards.

Install

The galapagos name on PyPI is squatted by an unrelated 2019 stub, so install from source:

pip install -e .                 # core: openai, pyyaml, pydantic, rich, python-dotenv
pip install -e ".[math]"         # numpy/scipy for numeric tasks
pip install -e ".[all]"          # every general-purpose extra at once
pip install -e ".[dev]"          # pytest, for the test suite

Full walkthrough: docs/content/installation.md.

Quickstart

Three cards and one call. Loaded by name, they're pulled straight from the registry — the same names you'd browse on the Hub:

import galapagos as gx

model    = gx.GalapagosModel.from_card(name="openai/gpt-5.5", host="openrouter")  # or name="mock" (offline)
scaffold = gx.GalapagosScaffold.from_card(name="openevolve", model=model)
task     = gx.GalapagosTask.from_card(name="circle_packing")
result   = scaffold.run(task=task)

print(result.best_score, result.summary)

Want to try it without spending anything? Set name="mock" — an offline model that performs real perturbations, so your run still improves without an API key. For a real LLM, set host to one of openai, openrouter, togetherai, litellm, vllm, huggingface, azure, or bedrock (export OPENAI_API_KEY first).

More in the quickstart guide.

The six components

Every method in Galapagos — yours included — is a composition of six components over the unit of evolution, the Genome (content, scores, metadata, artifacts).

#	Component	Role	Built-ins
1	Population	the store of evolved genomes (add / query / best)	InMemoryPopulation, IslandPopulation
2	SelectionPolicy	picks the parent + inspirations each step	ExploreExploitPolicy, UCBBanditPolicy, IdentityPolicy
3	PromptBuilder	renders the prompt — pure formatting, no selection	DefaultPromptBuilder
4	Proposer	the variation operator that produces a new genome	DiffProposer, CrossoverProposer
5	Evaluator	the pure scorer (supplied by the task)	SubprocessEvaluator
6	Memory	optional free-form knowledge (read / write)	NullMemory, ScratchpadMemory

The loop, in one sentence: select parents from the Population → build a prompt from them and Memory → propose a new candidate → evaluate it → add the scored Genome back to the Population → observe; repeat until the budget (max_iterations / target_score / max_usd / patience / wallclock_s) is hit.

Swap any slot. Keep the rest. That's a new method.

Deep dive: Concepts › Overview · Components · Genome · Models.

Build your own

Each slot takes an instance, a "module.Class" path, or a .py file — so a new method is usually a few keyword arguments, not a new codebase.

from galapagos.components import (
    IslandPopulation, ExploreExploitPolicy, DefaultPromptBuilder, DiffProposer, NullMemory,
)

scaffold = gx.GalapagosScaffold.from_card(
    population=IslandPopulation(num_islands=3),
    selection_policy=ExploreExploitPolicy(seed=0),
    prompt_builder=DefaultPromptBuilder(),
    proposer=DiffProposer(),
    memory=NullMemory(),
    model=gx.load_model("mock"),
)

When your method works, write it as a scaffold card and submit it. Guides: run a scaffold · custom scaffold · custom task.

Runnable now

8 bundled scaffolds, all runnable:

adaevolve   beam_search   best_of_n   best_of_n_attempts   evox   meta_harness   openevolve   topk

230+ bundled tasks. Quickstart-ready examples: circle_packing, function_minimization, playground_sphere.

Browse the registry from Python:

gx.available_scaffolds()    # every scaffold card
gx.available_tasks()        # every task card
gx.registered_scaffolds()   # the runnable subset (all 8)

Reference: API · scaffolds · tasks.

CLI

galapagos run --scaffold openevolve --task circle_packing --model mock --iters 20
galapagos scaffold list            # the scaffold catalog (all runnable)
galapagos task list                # the task catalog
galapagos submit --card card.yaml  # validate a scaffold/task card before hub submission

The Hub

The Hub (under hub/) turns cards into a community platform. Three pieces:

• Registry — browse and load scaffold cards, task cards, and model cards.
• Leaderboard — per-task rankings of scaffold × model runs, so every published number is apples-to-apples.
• Verification — submit a discovery as a VerificationCard (best solution + trajectory) for expert review. Status flows unverified → under_review → verified.

Read more: docs/content/hub.md · submitting to the Hub.

Examples

Runnable scripts and sample cards live in examples/:

File	What it shows
run_openevolve.py	a full OpenEvolve run
run_adaevolve.py	another method, same loop
build_your_own.py	composing a scaffold from the six components
run_with_real_model.py	pointing the loop at a hosted LLM

Sample cards: examples/model_card.yaml · examples/verification_card.yaml.

Documentation

Quickstart	Installation
Why Galapagos	Concepts: overview
Components · Genome	Cards · Models
Run a scaffold	Custom scaffold
Custom task	Submit to the Hub
API reference	Scaffolds · Tasks

Full site: galapagos.dev.

Contributing

Contributions are first-class: a new method is a scaffold card, a new benchmark is a task card, a new result is a verification card. See docs/content/contributing.md, validate any card with galapagos submit --card card.yaml, and open a PR. Issues and discussion are welcome.

License

Galapagos is released under the Apache-2.0 license.