Skip to content
Galapagos v0.3.0

Contributing

galapagos is built to be extended. The most valuable contributions are cards — a scaffold, a task, or a model — and method packages that ship a runnable scaffold class.

Set up

git clone https://github.com/minnesotanlp/open-galapagos-dev
cd open-galapagos-dev
pip install -e '.[dev]'          # adds pytest
pip install -e '.[math]'         # numpy/scipy, for the math tasks (optional)

The package is galapagos under src/galapagos/. Running a scaffold calls a live LLM, so set an OpenRouter key in OPENAI_API_KEY before you exercise the loop end-to-end (see Installation).

Contribute a card

A card is a portable artifact validated by a pydantic schema. Author the YAML, then validate it:

galapagos submit --card path/to/card.yaml      # validates against ScaffoldCard / TaskCard
  • Scaffold card → src/galapagos/scaffolds/<name>/card.yaml, co-located with the runnable code package (its config.yaml, README.md, and component modules) in the same folder. The card's controller field is a dotted Scaffold-subclass path. See Write your own scaffold and the card schema.
  • Task card → src/galapagos/tasks/<name>/{card.yaml, initial_program.py, evaluator.py}. See Write your own task.
  • Model card → a YAML with name / model_path / host, loaded via GalapagosModel.from_card(path=...).

Cards are permissive (extra="allow"), so you can add method-specific fields without touching the core schema.

Contribute a method package

A runnable method is a GalapagosScaffold subclass that overrides build_components, is decorated with @register_scaffold("name"), and ships a card.yaml (with controller) alongside its code, config.yaml, and README.md in one self-contained folder at src/galapagos/scaffolds/<name>/. The bundled OpenEvolveScaffold and AdaEvolveScaffold are the reference shape — keep new methods consistent with them. Third-party packages can also register via the galapagos.scaffolds entry-point group, and their cards load by explicit path (from_card(path=".../card.yaml")). Full walkthrough: Write your own scaffold.

Code style

  • Use the real public API. Compose from the six components; a Genome is the unit of evolution and genome.fitness == scores["combined_score"].
  • Keep the Evaluator on the task, never the scaffold.
  • Differentiate a method by which implementation fills each slot — not by adding architecture. Adaptation goes in the before_step / after_step / periodic hooks.
  • Match the existing module layout, docstring style, and type hints. Public surface stays small and importable from the top-level galapagos package.
  • Keep the core search path lightweight: never import torch on the frozen-search path.

Running the tests

The test suite lives under tests/ and runs with pytest:

pytest

Exercising a scaffold end-to-end calls a live LLM, so any test (or manual check) that runs the loop needs an OPENAI_API_KEY. Use the smallest task, playground_sphere, with a low --iters / max_iterations to keep the spend negligible. Build the docs locally with:

pip install mkdocs-material
mkdocs serve -f docs/mkdocs.yml

Submitting

Open a pull request against main. For a new scaffold or task, include its card(s). To put a discovery on the leaderboard rather than code, submit a VerificationCard to the Hub instead — see Submit to the Hub.