Use and contribute to Galapagos

This page is the shortest route from a fresh installation to the right Galapagos workflow. Choose one outcome first; each contribution type has its own directory, validator, pull-request template, and GitHub check.

I want to...	Follow this path	GitHub check
Run an existing method on an existing problem	Run Galapagos	none
Add a benchmark or optimization problem	Submit a task	submit-task
Add a search or evolution method	Submit a scaffold	submit-scaffold
Review somebody else's port of my work	Review a port	validate-task or validate-scaffold

For a complete method-porting example, continue with the ShinkaEvolve worked example.

Run Galapagos

Install the published package:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 'open-galapagos[math]'

Then choose three things:

• a model, which turns a prompt into a proposed edit;
• a scaffold, which controls the search method; and
• a task, which owns the problem, seed, evaluator, and score.

galapagos run \
  --scaffold topk \
  --task function_minimization \
  --proposer.model_name openai/gpt-4o-mini \
  --general.eval_mode local \
  --general.max_iterations 3

Use these commands to discover what is installed:

galapagos scaffold list
galapagos task list
galapagos run --help

The Quickstart explains the first run in more detail, and Run a scaffold covers configuration, Docker evaluation, checkpoints, and output artifacts.

Understand the two submission destinations

“Submit” can mean two different things:

Destination	Purpose	Result
GitHub pull request	Add a task or scaffold to the Galapagos source catalog	Reviewed code merged into the repository
Galapagos Hub	Publish a portable card-and-assets bundle	Browsable/downloadable Hub artifact

A GitHub contribution belongs under src/galapagos/tasks/ or src/galapagos/scaffolds/. Its PR validator exercises the real Hub bundle collector with galapagos submit --dry-run, so undeclared local files cannot make a broken submission appear valid.

To upload an artifact without adding it to the source catalog, follow Submit to the Hub.

Prepare a contribution checkout

Fork Open-Galapagos/galapagos-dev, then create one focused branch from the latest upstream main:

git clone https://github.com/<YOUR_GITHUB_USERNAME>/galapagos-dev.git
cd galapagos-dev
git remote add upstream https://github.com/Open-Galapagos/galapagos-dev.git
git fetch upstream
git switch -c contrib/<short-name> upstream/main

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[math,dev]'

Use a lowercase filesystem-safe slug such as my_task or my_scaffold. The directory name and card.yaml's name must match.

Submit a task

A task owns the problem statement, seed program, evaluator, metrics, and reproducible scoring environment:

src/galapagos/tasks/my_task/
├── card.yaml
├── README.md
├── initial_program.py
├── evaluator.py
└── Dockerfile

The evaluator must expose evaluate(program_path) -> dict, independently recompute the verdict, and return a finite combined_score. Never trust a score claimed by candidate code. Every component and support file must be present in the upload bundle.

Run the exact PR gate locally:

python scripts/validate_task_submission.py src/galapagos/tasks/my_task

Commit only the task directory and open the PR with .github/PULL_REQUEST_TEMPLATE/task_submission.md. A focused task PR triggers submit-task, not any scaffold or upstream-review check.

See Write your own task for the complete card, evaluator, asset, and Docker contracts.

Submit a scaffold

A scaffold maps a method onto six stable slots:

1. Population
2. SelectionPolicy
3. PromptBuilder
4. Proposer
5. Evaluator — always supplied by the task
6. Memory

Create a self-contained directory. Reuse existing components when the method does not change them; only genuinely new behavior needs a new class.

src/galapagos/scaffolds/my_scaffold/
├── __init__.py
├── card.yaml
├── README.md
├── config.yaml
├── scaffold.py
└── selection_policy.py

The card declares all six roles. The controller's build_components() returns the five scaffold-owned runtime objects and must not return an evaluator.

python scripts/validate_scaffold_submission.py \
  src/galapagos/scaffolds/my_scaffold

The validator checks the real dry-run bundle, imports the controller, builds its components without a paid model call, and verifies each Galapagos interface. Open the PR with .github/PULL_REQUEST_TEMPLATE/scaffold_submission.md; a focused scaffold PR triggers only submit-scaffold.

See Build your own scaffold for the component API and Submit a new scaffold for Hub bundle details.

Review a port

If a contributor ported somebody else's repository or paper, the normal submit-task or submit-scaffold PR proves portability, not research fidelity. The contributor should:

• identify the canonical repository, paper, and studied commit;
• preserve the upstream license and notices;
• state exact mappings and approximations separately; and
• avoid implying upstream ownership or endorsement.

An upstream author or maintainer can later create a separate executable review:

cp -r porting_reviews/templates/task \
  porting_reviews/tasks/<task-slug>

# or
cp -r porting_reviews/templates/scaffold \
  porting_reviews/scaffolds/<scaffold-slug>

Those review-only PRs run validate-task or validate-scaffold. Read Review a port as an upstream author for the manifest, identity check, and test contract.

Final checklist

Before opening any contribution PR:

git status --short
git diff --check

• Keep one task, scaffold, or review type per PR.
• Include every file referenced by the card.
• Paste the local validator summary into the PR.
• Do not put GitHub, model-provider, or Hub tokens in cards, code, shell commands committed to history, or PR descriptions.

The repository-level GUIDE.md contains copyable card and controller skeletons for the same workflow.