Skip to content

Open-ended program evolution

ShinkaEvolve

Evolve scientific code with LLM-guided mutation, archive-based search, async proposal pipelines, and local or cluster-backed evaluation.

GET STARTED API REFERENCE BLOG PAPER

Why ShinkaEvolve

ShinkaEvolve combines LLM mutation operators with an evolutionary archive, parallel evaluation, and a reproducible task contract. The repository gives you both the framework primitives and runnable examples — start from a simple evaluate.py + initial.py task and scale up to async runs or cluster workflows.

Runtime

ShinkaEvolveRunner handles async evolution, proposal/eval concurrency, prompt co-evolution, and resumable runs.

Config

Runtime dataclasses, Hydra presets, and agent-oriented shinka_run overrides. Compose at any level.

Execution

Run locally, source a project env per job, or launch on SLURM with Conda or Docker-backed workers.

Inspection

Lineages, metrics, diffs, throughput, and prompt evolution artifacts in the built-in WebUI.

Quickstart

pip install shinka-evolve
shinka_launch variant=circle_packing_example

The distribution name is shinka-evolve; the import path is import shinka. For source installs and a full first-run walkthrough, see Getting Started.

Two Entry Paths

Hydra Launcher

Shared Hydra presets, compact override syntax, config-composed workflow:

shinka_launch \
  task=circle_packing \
  database=island_large \
  evolution=small_budget \
  cluster=local \
  evo_config.num_generations=20

Agent-Friendly CLI

Task directory as the interface — explicit flags, no Hydra group files:

shinka_run \
  --task-dir examples/circle_packing \
  --results_dir results/circle_agent_run \
  --num_generations 20 \
  --set db.num_islands=2

The CLI split and precedence rules are documented in CLI Usage.

Page Content
Getting Started Install, first run, API usage, troubleshooting
Core Concepts Task contract, async loop, archives, islands
Configuration Runtime dataclasses, presets, override grammar
API Reference Curated reference for runtime modules
Examples Runnable tasks and recommended entry points