Metadata-Version: 2.4
Name: open-galapagos
Version: 0.3.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.3.0](https://img.shields.io/badge/version-0.3.0-1c6b4d?style=flat-square)](pyproject.toml)
[![Scaffolds 8](https://img.shields.io/badge/scaffolds-8-1c6b4d?style=flat-square)](#runnable-now)
[![Tasks 230+](https://img.shields.io/badge/tasks-230%2B-1c6b4d?style=flat-square)](#runnable-now)
[![Docs](https://img.shields.io/badge/docs-galapagos.dev-1f9e92?style=flat-square)](https://galapagos.dev)

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

</div>

---

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.

```python
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](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

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

```bash
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](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")  # 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](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("mock"),
)
```

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

**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:

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

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 --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/`](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

Runnable scripts and sample cards live in [`examples/`](examples/):

| File | What it shows |
| --- | --- |
| [`run_openevolve.py`](examples/run_openevolve.py) | a full OpenEvolve run |
| [`run_adaevolve.py`](examples/run_adaevolve.py) | another method, same loop |
| [`build_your_own.py`](examples/build_your_own.py) | composing a scaffold from the six components |
| [`run_with_real_model.py`](examples/run_with_real_model.py) | pointing the loop at a hosted LLM |

Sample cards: [`examples/model_card.yaml`](examples/model_card.yaml) · [`examples/verification_card.yaml`](examples/verification_card.yaml).

## 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: [**galapagos.dev**](https://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](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.
