Metadata-Version: 2.4
Name: open-galapagos
Version: 0.4.0
Summary: A user-friendly, open-source platform for LLM-driven evolutionary search on scientific-discovery tasks.
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.40
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.5
Requires-Dist: rich>=13.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: math
Requires-Dist: numpy; extra == "math"
Requires-Dist: scipy; extra == "math"
Provides-Extra: algotune
Requires-Dist: open-galapagos[math]; extra == "algotune"
Requires-Dist: cvxpy>=1.6; extra == "algotune"
Requires-Dist: ortools==9.12.4544; extra == "algotune"
Requires-Dist: scikit-learn>=1.6; extra == "algotune"
Requires-Dist: python-sat==1.8.dev17; extra == "algotune"
Requires-Dist: pot>=0.9; extra == "algotune"
Requires-Dist: faiss-cpu>=1.8; extra == "algotune"
Requires-Dist: hdbscan>=0.8.33; extra == "algotune"
Requires-Dist: highspy>=1.7; extra == "algotune"
Requires-Dist: ecos>=2.0.12; extra == "algotune"
Requires-Dist: networkx>=3.2; extra == "algotune"
Requires-Dist: sympy>=1.13; extra == "algotune"
Requires-Dist: numba>=0.59; extra == "algotune"
Requires-Dist: mpmath>=1.3; extra == "algotune"
Requires-Dist: cryptography>=42; extra == "algotune"
Requires-Dist: threadpoolctl>=3.1; extra == "algotune"
Provides-Extra: frontiercs
Requires-Dist: requests>=2.28; extra == "frontiercs"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Provides-Extra: all
Requires-Dist: open-galapagos[math]; extra == "all"
Requires-Dist: open-galapagos[algotune]; extra == "all"
Requires-Dist: open-galapagos[frontiercs]; extra == "all"
Dynamic: license-file

<div align="center">

<img src="design_assets/logo_icon/mark-transparent-512.png" width="120" alt="Galapagos"/>

# Galapagos 🐢

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-1c6b4d?style=flat-square)](https://www.python.org/)
[![License Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-1c6b4d?style=flat-square)](LICENSE)
[![Version 0.4.0](https://img.shields.io/badge/version-0.4.0-1c6b4d?style=flat-square)](pyproject.toml)
[![Scaffolds 10](https://img.shields.io/badge/scaffolds-10-1c6b4d?style=flat-square)](#runnable-now)
[![Tasks 945](https://img.shields.io/badge/tasks-945-1c6b4d?style=flat-square)](#runnable-now)
[![Docs](https://img.shields.io/badge/docs-open--galapagos.com-1f9e92?style=flat-square)](https://open-galapagos.com)

[Docs](https://open-galapagos.com) · [Quickstart](docs/content/quickstart.md) · [Concepts](docs/content/concepts/overview.md) · [The Hub](docs/content/hub.md) · [Examples](examples/)

</div>

---

Any LLM × **10 scaffolds** × **945 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.

```python
import galapagos as gx

model    = gx.GalapagosModel.from_card(name="openai/gpt-5.5", host="openrouter")
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.

Set `host` to any OpenAI-compatible provider — `openrouter` (default), `openai`, `anthropic`, `gemini`, `azure`, `vllm`, or `litellm` — and export a key. No provider key? The `claude_code` scaffold runs the whole loop through a local Claude Code CLI session, billed to your Claude subscription instead.

## 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](docs/content/motivation.md).)

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](docs/content/concepts/cards.md).

## Install

Published on PyPI as **`open-galapagos`** (the bare `galapagos` name is an unrelated 2019 stub) — you still `import galapagos`:

```bash
pip install open-galapagos                # core: openai, pyyaml, pydantic, rich, python-dotenv
pip install "open-galapagos[math]"        # numpy/scipy for numeric tasks
pip install "open-galapagos[all]"         # every general-purpose extra (math + algotune + frontiercs)
```

Or an editable checkout for development: `pip install -e ".[all]"`.

Full walkthrough: [docs/content/installation.md](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:

```python
import galapagos as gx

model    = gx.GalapagosModel.from_card(name="openai/gpt-5.5", host="openrouter")
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)
```

Set `host` to one of `openai`, `openrouter` (default), `anthropic`, `gemini`, `azure`, `vllm`, or `litellm`, and export `OPENAI_API_KEY` (or the provider's own key) first. Don't want to use a provider key? The `claude_code` and `claude_code_docker` scaffolds run the loop through a local Claude Code CLI session, billed to your Claude subscription instead.

More in the [quickstart guide](docs/content/quickstart.md).

## 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](docs/content/concepts/overview.md) · [Components](docs/content/concepts/components.md) · [Genome](docs/content/concepts/genome.md) · [Models](docs/content/concepts/models.md).

## 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.

```python
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("openai/gpt-5.5", host="openrouter"),
)
```

When your method works, write it as a **scaffold card** and submit it. Guides: [run a scaffold](docs/content/guides/run-a-scaffold.md) · [custom scaffold](docs/content/guides/custom-scaffold.md) · [custom task](docs/content/guides/custom-task.md).

## Runnable now

**10 bundled scaffolds, all runnable:**

```
adaevolve   beam_search   best_of_n   best_of_n_attempts   claude_code   claude_code_docker   evox   meta_harness   openevolve   topk
```

**945 bundled tasks** across many benchmark suites — symbolic regression (241), FrontierCS (188), AlgoTune (154), GPU MODE kernels (47), AlphaEvolve math discovery (46), ALE-Bench (40), Open Problems single-cell (15), and more ([what each needs](docs/content/installation.md#what-the-bundled-suites-need)). Quickstart-ready examples: `circle_packing`, `function_minimization`, `playground_sphere`.

Browse the registry from Python:

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

Reference: [API](docs/content/reference/api.md) · [scaffolds](docs/content/reference/scaffolds.md) · [tasks](docs/content/reference/tasks.md).

## CLI

```bash
galapagos run --scaffold openevolve --task circle_packing --proposer.model_name openai/gpt-5.5 --general.max_iterations 20
galapagos run --scaffold openevolve --task circle_packing --resume runs/prev   # continue from a checkpoint
galapagos scaffold list                       # the scaffold catalog (all runnable)
galapagos task list                           # the task catalog
galapagos submit --card card.yaml --dry-run   # validate + preview the bundle (drop --dry-run to upload)
```

## The Hub

The Hub (under [`hub/`](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](docs/content/hub.md) · [submitting to the Hub](docs/content/guides/hub-submit.md).

## Examples

The [`examples/`](examples/) folder carries a worked **scaffold card** — [`shinkaevolve/`](examples/shinkaevolve/) — showing how a published method (ShinkaEvolve) is expressed as a `card.yaml` + `README.md` you can load by path or submit to the Hub. For end-to-end walkthroughs, start with the [Quickstart](docs/content/quickstart.md) and the guides above.

## Documentation

| | |
| --- | --- |
| [Quickstart](docs/content/quickstart.md) | [Installation](docs/content/installation.md) |
| [Why Galapagos](docs/content/motivation.md) | [Concepts: overview](docs/content/concepts/overview.md) |
| [Components](docs/content/concepts/components.md) · [Genome](docs/content/concepts/genome.md) | [Cards](docs/content/concepts/cards.md) · [Models](docs/content/concepts/models.md) |
| [Run a scaffold](docs/content/guides/run-a-scaffold.md) | [Custom scaffold](docs/content/guides/custom-scaffold.md) |
| [Custom task](docs/content/guides/custom-task.md) | [Submit to the Hub](docs/content/guides/hub-submit.md) |
| [API reference](docs/content/reference/api.md) | [Scaffolds](docs/content/reference/scaffolds.md) · [Tasks](docs/content/reference/tasks.md) |

Full site: [**open-galapagos.com**](https://open-galapagos.com).

## 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](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) license.
