### Run Shinka examples via CLI (Bash)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Executes the circle packing example with default settings or custom parameters using the Hydra-based CLI launcher.

```Bash
# Run circle packing example with default settings
shinka_launch variant=circle_packing_example

# Run with custom parameters
shinka_launch \
    task=circle_packing \
    database=island_small \
    evolution=small_budget \
    cluster=local \
    evo_config.num_generations=5
```

--------------------------------

### Launch Shinka Experiments via CLI (Bash)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

These commands use the shinka_launch tool to run evolutionary examples, with options for variants, custom settings, or direct Python execution. Depends on Shinka CLI installation and example files. Inputs include command-line arguments for tasks and configs; outputs initiate local or cluster runs. Limitations: Custom settings require knowledge of config parameters; not suitable for interactive debugging.

```Bash
# Using CLI launcher (recommended)
shinka_launch variant=circle_packing_example

# Or with custom settings
shinka_launch \
    task=circle_packing \
    cluster=local \
    evo_config.num_generations=20 \
    db_config.num_islands=4

# Or just via the python API
python run_evo.py
```

--------------------------------

### Verify Shinka installation (Bash)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Runs the CLI launcher help command and a quick Python import test to confirm the installation.

```Bash
# Test the CLI launcher
shinka_launch --help

# Test Python imports
python -c "from shinka.core import EvolutionRunner; print('Installation successful!')"
```

--------------------------------

### Initialize and Run EvolutionRunner (Python)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

This code initializes an EvolutionRunner instance with configuration objects and starts the evolutionary optimization process. It depends on Shinka library configurations for evolution, jobs, and database. Inputs are the config objects; outputs include the execution of generations with results stored in the database. Limitations: Requires pre-defined config objects and may need cluster setup for distributed runs.

```Python
runner = EvolutionRunner(
    evo_config=evo_config,
    job_config=job_config,
    db_config=db_config,
)
runner.run()
```

--------------------------------

### Install Shinka using uv (Bash)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Installs uv, clones the repository, creates a Python 3.11 virtual environment, activates it, and installs Shinka in editable mode using uv's pip. Requires curl or PowerShell on Windows.

```Bash
# Install uv on macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install uv on Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or install via pip
pip install uv

# Clone and install Shinka
git clone <shinka-repository-url>
cd ShinkaEvolve

# Create virtual environment with Python 3.11
uv venv --python 3.11

# Activate the environment
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate   # On Windows

# Install Shinka in development mode
uv pip install -e .
```

--------------------------------

### Advanced uv features (Bash)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Generates a lockfile for reproducible environments, installs development dependencies, and syncs the environment to exactly match pyproject.toml.

```Bash
# Generate uv.lock file
uv pip compile pyproject.toml --output-file requirements.lock

# Install from lockfile
uv pip install -r requirements.lock

# Install development dependencies (includes pytest, black, etc.)
uv pip install -e '.[dev]'

# Sync environment to match pyproject.toml exactly
uv pip sync pyproject.toml
```

--------------------------------

### Install Shinka using conda/pip (Bash)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Creates a conda environment with Python 3.11, activates it, clones the repository and installs Shinka in editable mode using pip.

```Bash
# Create conda environment
conda create -n shinka python=3.11
conda activate shinka

# Clone and install Shinka
git clone <shinka-repository-url>
cd ShinkaEvolve
pip install -e .
```

--------------------------------

### Run Shinka using Python API (Python)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Uses the Python API to configure job execution, database, and evolution parameters, then runs the EvolutionRunner.

```Python
from shinka.core import EvolutionRunner, EvolutionConfig
from shinka.database import DatabaseConfig
from shinka.launch import LocalJobConfig

# Configure the job execution environment
job_config = LocalJobConfig(
    eval_program_path="examples/circle_packing/evaluate.py",
    conda_env="my_special_env",  # Optional: run in specific conda environment
)

# Configure the evolution database
db_config = DatabaseConfig(
    archive_size=20,
    num_archive_inspirations=4,
    num_islands=2,
    migration_interval=10,
)

# Configure the evolution parameters
evo_config = EvolutionConfig(
    num_generations=10,
    max_parallel_jobs=1,
    llm_models=["azure-gpt-4.1"],
    init_program_path="examples/circle_packing/initial.py",
    language="python",
    task_sys_msg="You are optimizing circle packing...",
)

```

--------------------------------

### Create .env credentials (Bash)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Creates a .env file containing API keys for OpenAI and optionally Anthropic.

```Bash
# .env file
OPENAI_API_KEY=sk-proj-your-key-here
ANTHROPIC_API_KEY=your-anthropic-key-here  # Optional
```

--------------------------------

### Verify API Key Configuration

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Checks that API keys are properly configured by examining the .env file and verifying environment variables. Essential for ensuring proper authentication with external services.

```bash
# Verify .env file exists and contains valid keys
cat .env
# Check environment variables
python -c "import os; print(os.getenv('OPENAI_API_KEY'))"
```

--------------------------------

### Enable Debug Mode

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Enables verbose logging for troubleshooting issues during evolutionary runs. Provides detailed output that can help identify problems with configuration, environment, or execution.

```bash
shinka_launch variant=my_variant verbose=true
```

--------------------------------

### Start experiment and WebUI locally

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Launches a Shinka evolution experiment and opens the WebUI in a browser for real-time monitoring.

```bash
# Start your evolution experiment
shinka_launch variant=circle_packing_example

# In another terminal, launch the WebUI
shinka_visualize --port 8888 --open

# Or specify a results directory
shinka_visualize results_20241201_120000/ --port 8888 --open

# Or target a specific database file
shinka_visualize --db results_20241201_120000/evolution_db.sqlite --port 8888 --open

# Open browser to http://localhost:8888 (if not auto-opened)
```

--------------------------------

### Manage Conda Environments for Local Jobs

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Verifies and manages conda environments for local job execution. Includes commands to list environments, test environment functionality, check package installations, and install the shinka package in specific environments.

```bash
# Verify conda environment exists
conda env list

# Test conda environment works
conda run -n my_env python --version

# Check if required packages are installed in target environment
conda run -n my_env python -c "import shinka; print('OK')"

# Install shinka in specific conda environment
conda activate my_env
pip install -e .
conda deactivate
```

--------------------------------

### Generate Code Evolution Animation

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Creates animations showing how code evolves over generations using the results directory from a completed run. Useful for visualizing the evolutionary process and understanding how solutions improve over time.

```bash
python code_path_anim.py --results_dir examples/circle_packing/results_20250101_120000
```

--------------------------------

### Set Up Evaluation Script Main Function (Python)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

The main function in evaluate.py orchestrates testing of evolved solutions using Shinka's run_shinka_eval. Depends on Shinka core module and custom functions for kwargs, validation, and metrics. Inputs: program path and results directory; outputs: metrics dict, correctness bool, and error message. Limitations: Relies on defined experiment, validation, and metrics functions; single run by default.

```Python
from shinka.core import run_shinka_eval

def main(program_path: str, results_dir: str):
    """Main evaluation function called by Shinka"""

    metrics, correct, error_msg = run_shinka_eval(
        program_path=program_path,
        results_dir=results_dir,
        experiment_fn_name="run_packing",        # Function to call in evolved code
        num_runs=1,                              # Number of test runs
        get_experiment_kwargs=get_kwargs_fn,     # Arguments for each run
        validate_fn=validation_function,         # Validation logic
        aggregate_metrics_fn=metrics_function,   # Metrics computation
    )
```

--------------------------------

### Resume Evolution Run with CLI

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Extends an existing evolutionary run to a specified number of generations using the command line interface. The num_generations parameter should represent the total desired generations, not additional ones. Requires a valid results directory from a previous run.

```bash
# Resume an existing run and extend to 50 generations
shinka_launch \
    variant=circle_packing_example \
    evo_config.results_dir=results_20250101_120000 \
    evo_config.num_generations=50

# Or with a custom task
shinka_launch \
    task=circle_packing \
    database=island_small \
    evolution=small_budget \
    cluster=local \
    evo_config.results_dir=path/to/previous/results \
    evo_config.num_generations=100
```

--------------------------------

### Resume Evolution Run with Python API

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Uses the Python API to resume an existing evolutionary run by pointing to a previous results directory. The num_generations parameter should be the total desired generations. Database configuration must match the original run to preserve progress and meta-recommendations.

```python
from shinka.core import EvolutionRunner, EvolutionConfig
from shinka.database import DatabaseConfig
from shinka.launch import LocalJobConfig

# Point to existing results directory
evo_config = EvolutionConfig(
    num_generations=50,  # Extend to 50 total generations
    results_dir="results_20250101_120000",  # Existing results
    # ... other config parameters ...
)

job_config = LocalJobConfig(
    eval_program_path="examples/circle_packing/evaluate.py",
)

db_config = DatabaseConfig(
    archive_size=20,
    num_islands=2,
)

# Run will automatically detect and resume
runner = EvolutionRunner(
    evo_config=evo_config,
    job_config=job_config,
    db_config=db_config,
)
runner.run()
```

--------------------------------

### Aggregate Metrics for Evaluation (Python)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

This function computes fitness scores and structures results into public and private metrics for Shinka analysis. Depends on results list and helper functions like format_centers. Inputs: results array and results_dir; outputs: dict with combined_score, public, and private keys. Limitations: Assumes single result extraction; computation_time is hardcoded example.

```Python
def aggregate_metrics(results, results_dir):
    """Returns metrics dictionary with required structure"""

    # Extract data from results
    centers, radii, reported_sum = results[0]

    return {
        "combined_score": float(reported_sum),    # PRIMARY FITNESS (higher = better)
        "public": {                               # Visible in WebUI/logs
            "num_circles": len(centers),
            "centers_str": format_centers(centers)
        },
        "private": {                              # Internal analysis only
            "reported_sum_of_radii": float(reported_sum),
            "computation_time": 0.15
        }
    }
```

--------------------------------

### Install ShinkaEvolve

Source: https://github.com/sakanaai/shinkaevolve/blob/main/README.md

Instructions for cloning the repository, installing dependencies, and activating the virtual environment. This sets up the environment for running ShinkaEvolve locally.

```bash
git clone https://github.com/SakanaAI/ShinkaEvolve
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create environment and install Shinka
cd ShinkaEvolve
uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Run your first evolution experiment
shinka_launch variant=circle_packing_example
```

--------------------------------

### Google Colab Setup

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

This code snippet installs the Shinka package within a Google Colab instance. It clones the repository and installs dependencies, ensuring the environment is ready for experimentation.  It also checks if running locally.

```python
import os
import sys
import subprocess
from pathlib import Path

# detect colab
try:
    import google.colab  # type: ignore

in_colab = True
except Exception:
    in_colab = False

repo_name = "ShinkaEvolve"
ssh_url = "git@github.com:SakanaAI/ShinkaEvolve.git"
https_url = "https://github.com/SakanaAI/ShinkaEvolve.git"

cwd = Path.cwd()
repo_root = cwd

if not (repo_root / repo_name).exists():
    for parent in cwd.resolve().parents:
        if (parent / repo_name).exists():
            repo_root = parent
            break

if in_colab:
    root_candidate = Path("/content") / repo_name
    if not root_candidate.exists():
        print("cloning repository...")
        subprocess.check_call([
            "git",
            "clone",
            "--depth",
            "1",
            https_url,
            str(root_candidate),
        ])
    repo_root = root_candidate
    os.chdir(repo_root)
    print("repo_root:", repo_root)
    print("installing package and deps...")
    subprocess.check_call([sys.executable, "-m", "pip", "install", "-e", "."])
else:
    print("repo_root:", repo_root)

```

--------------------------------

### Resolve uv-Specific Issues

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Addresses common issues with the uv package manager including version checks, virtual environment verification, environment reset, and cache cleaning. Helpful when experiencing dependency resolution problems.

```bash
# Check uv version
uv --version

# Verify virtual environment is activated
which python  # Should point to .venv/bin/python

# Reset environment if needed
rm -rf .venv
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e .

# Check uv cache if having dependency issues
uv cache clean
```

--------------------------------

### Fix Import Errors

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Resolves common import errors by ensuring the package is properly installed in development mode. Includes commands for both uv and pip package managers, plus verification of the Python path.

```bash
# If using uv
uv pip install -e .
# If using pip
pip install -e .
# Check Python path
python -c "import shinka; print(shinka.__file__)"
```

--------------------------------

### Configure Local Job Environment

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

Configures Python environments for local job execution. Supports using the current environment or specifying a conda environment. Useful for isolating evaluation environments and testing compatibility across different package versions.

```python
job_config = LocalJobConfig(
    eval_program_path="evaluate.py"
)
# Uses the currently active Python environment
```

```python
job_config = LocalJobConfig(
    eval_program_path="evaluate.py",
    conda_env="my_project_env"  # Runs in specified conda environment
)
```

--------------------------------

### Run sync evolution and launch WebUI

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Starts a synchronous evolution process and launches the WebUI with a specific results directory or database file.

```bash
python run_evo.py        # Start sync evolution

# Launch WebUI with specific results directory
shinka_visualize results_20241201_120000/ --open

# Or with specific database file
shinka_visualize --db results_20241201_120000/evolution_db.sqlite --open
```

--------------------------------

### Define Initial Circle Packing Construction (Python)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

This function provides the starting solution for evolving circle arrangements in a unit square, marked for LLM modification during evolution. Depends on NumPy for array operations. Inputs: None (fixed n=26); outputs: centers and radii arrays. Limitations: Placeholder logic needs evolution; assumes 2D unit square bounds.

```Python
# EVOLVE-BLOCK-START
def construct_packing():
    """Construct arrangement of 26 circles in unit square"""
    # This code will be modified by the LLM
    n = 26
    centers = np.zeros((n, 2))
    # ... placement logic ...
    return centers, radii
# EVOLVE-BLOCK-END
```

--------------------------------

### Launch WebUI with default settings

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Starts the WebUI using default configurations. Requires Python 3.8+ and an accessible SQLite database. The server runs on port 8000 by default.

```bash
shinka_visualize
```

--------------------------------

### Launch WebUI with results directory

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Starts the WebUI using a specific results directory, custom port, and auto-opens the browser. Ideal for viewing specific experiment outputs.

```bash
shinka_visualize /path/to/results_directory/ --port 8888 --open
```

--------------------------------

### Run async evolution and launch WebUI

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Starts an asynchronous evolution process and launches the WebUI to monitor it. Auto-detection of the database is used unless specified.

```bash
python run_evo_async.py  # Start async evolution

# Launch WebUI (auto-detects database in current directory)
shinka_visualize --open
```

--------------------------------

### Launch WebUI with specific database path

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Starts the WebUI pointing to a specific SQLite database file. Useful for analyzing archived experiments.

```bash
shinka_visualize --db /path/to/evolution_db.sqlite
```

--------------------------------

### Launch WebUI Locally - Python

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

Starts the Shinka visualization web server as a background subprocess on local machine. Uses subprocess to run shinka_visualize with options. Inputs: Port (8888), open flag. Outputs: Prints success message; process runs in background. Requires shinka_visualize installed; sleep ensures startup time.

```python
import sys, subprocess, time

# start the webui as a background process
webui_proc = subprocess.Popen(
    ["shinka_visualize", "--port", "8888", "--open"],
    stdout=subprocess.PIPE,
    stderr=subprocess.STDOUT,
    text=True,
)

# wait briefly so server has time to start
time.sleep(3)
print("webui started on http://127.0.0.1:8888")
```

--------------------------------

### YAML Configuration for Quick Prototyping Setup

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/configuration.md

A streamlined YAML configuration for rapid prototyping and development. It employs small-budget defaults for database, evolution, and cluster, limiting generations and parallel jobs for faster iteration.

```yaml
# Fast iteration for development
defaults:
  - override /database@_global_: island_small
  - override /evolution@_global_: small_budget
  - override /cluster@_global_: local

evo_config:
  num_generations: 5
  max_parallel_jobs: 1

db_config:
  num_islands: 1
  archive_size: 10

variant_suffix: "_prototype"

```

--------------------------------

### Custom Variant File Creation in YAML

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/configuration.md

This example creates a custom YAML variant by combining small island database, small budget evolution, and a custom task on local cluster, with overrides for generations and migration. It uses Hydra defaults system. Inputs: Existing configs plus custom params. Outputs: Flexible experiment setup. Limitations: Requires compatible task definition; test overrides for validity.

```yaml
# configs/variant/my_custom_variant.yaml
 defaults:
  - override /database@_global_: island_small
  - override /evolution@_global_: small_budget
  - override /task@_global_: my_task
  - override /cluster@_global_: local
  - _self_

 # Override specific parameters
 evo_config:
  num_generations: 25
  max_parallel_jobs: 2

 db_config:
  archive_size: 30
  migration_interval: 5

 variant_suffix: "_custom"
```

--------------------------------

### Launch WebUI and auto-open browser

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Starts the WebUI and automatically opens the default browser to view the dashboard. Requires browser access on the host machine.

```bash
shinka_visualize --open
```

--------------------------------

### Embed WebUI in Jupyter notebook

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

This snippet shows how to start the WebUI server and embed it in a Jupyter notebook using an IFrame.

```python
from IPython.display import IFrame
import subprocess
import time

subprocess.Popen(['shinka_visualize', '--port', '8888'])
time.sleep(2)

IFrame('http://localhost:8888', width=1000, height=600)
```

--------------------------------

### Launching Evolution with Bash

Source: https://github.com/sakanaai/shinkaevolve/blob/main/README.md

Bash commands for launching evolutionary experiments using the shinka_launch script with Hydra configuration. Supports pre-configured variants or custom overrides for task, database, evolution, cluster, and evo_config parameters. Inputs are command-line arguments; outputs launch the experiment. Requires Hydra and shinka installation; limited by available configurations in the guide.

```bash
# Run with pre-configured variant
shinka_launch variant=circle_packing_example

# Run with custom parameters
shinka_launch \
    task=circle_packing \
    database=island_large \
    evolution=small_budget \
    cluster=local \
    evo_config.num_generations=20
```

--------------------------------

### Handle large experiments

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

This snippet shows how to launch the WebUI for large experiments with many generations.

```bash
shinka_visualize large_experiment_results/ --port 8888 --open

shinka_visualize --db large_experiment_results/evolution_db.sqlite --port 8888
```

--------------------------------

### Enable verbose logging

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

This snippet demonstrates how to launch the WebUI with verbose output for debugging purposes.

```bash
shinka_visualize --port 8888
```

--------------------------------

### YAML Configuration for Production Research Setup

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/configuration.md

Configuration tailored for large-scale production research experiments. It utilizes large-budget defaults for database, evolution, and cluster, with increased generations, parallel jobs, and islands for extensive exploration.

```yaml
# Large-scale research experiment
defaults:
  - override /database@_global_: island_large
  - override /evolution@_global_: large_budget
  - override /cluster@_global_: remote

evo_config:
  num_generations: 100
  max_parallel_jobs: 8

db_config:
  num_islands: 8
  archive_size: 50
  migration_interval: 5

variant_suffix: "_production"

```

--------------------------------

### Troubleshoot database not found

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

This snippet shows how to specify the database path explicitly when the WebUI cannot find the default evolution_db.sqlite file.

```bash
shinka_visualize --db /full/path/to/evolution_db.sqlite
```

--------------------------------

### Monitor multiple experiments simultaneously

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

This snippet demonstrates how to run and access multiple WebUI instances on different ports for monitoring multiple experiments.

```bash
shinka_visualize exp1/ --port 8888

shinka_visualize exp2/ --port 8889

shinka_visualize --db exp1/evolution_db.sqlite --port 8888
shinka_visualize --db exp2/evolution_db.sqlite --port 8889
```

--------------------------------

### Command Line Configuration with Shinka Launcher

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

Examples of using the shinka_launch command-line interface to quickly configure and run experiments with preset configurations, including task selection, database settings, and evolution parameters.

```bash
shinka_launch \
    task=circle_packing \
    database=island_large \
    evolution=small_budget \
    cluster=local \
    evo_config.num_generations=10 \
    db_config.num_archive_inspirations=2 \
    variant_suffix="_fast"
```

```bash
shinka_launch variant=circle_packing_example
```

--------------------------------

### Environment Setup

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

This script sets up the repository, adds it to the Python path, and loads environment variables from a `.env` file (if present). It also allows overriding environment variables with additional LLM keys.

```python
import sys
import os
from pathlib import Path

repo_root = Path.cwd()
if not (repo_root / "shinka").exists():
    for parent in Path.cwd().resolve().parents:
        if (parent / "shinka").exists():
            repo_root = parent
            break

sys.path.insert(0, str(repo_root))
print("repo_root:", repo_root)

env_path = repo_root / ".env"
if env_path.exists():
    try:
        from dotenv import load_dotenv

        load_dotenv(env_path)
        print("loaded .env")
    except Exception as e:
        print("could not load .env:", e)
else:
    print(".env not found, continuing without it)")

# override with your own keys not present in .env file
additional_llm_keys = [
    # "OPENAI_API_KEY=...",
    # "GEMINI_API_KEY=...",
    # "OPENROUTER_API_KEY=...",
    # "DEEPSEEK_API_KEY=...",
    # "AZURE_OPENAI_API_KEY=...",
    # "ANTHROPIC_API_KEY=...",
]

for kv in additional_llm_keys:
    if "=" in kv:
        key, val = kv.split("=", 1)
        if val:
            os.environ[key] = val
            print(f"set {key}")

```

--------------------------------

### Shinka Configuration Example

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

This code snippet demonstrates setting up a custom Shinka configuration, importing necessary modules, and configuring database and job settings for evolutionary experiments.

```python
# standard shinka imports
import os
import datetime as dt
from time import perf_counter
from pathlib import Path
from shinka.core import EvolutionRunner, EvolutionConfig
from shinka.database import DatabaseConfig
from shinka.launch import LocalJobConfig
```

--------------------------------

### Python API for Configuration Management

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

Shows how to load preset configurations programmatically using the Python API and integrate them with EvolutionRunner for automated experiment execution.

```python
from shinka.launch.utils import build_cfgs_from_python

launcher_args = [
    "variant=circle_packing_example",
]

job_cfg, db_cfg, evo_cfg, cfg = build_cfgs_from_python(*launcher_args)

evo_runner = EvolutionRunner(
    evo_config=evo_cfg,
    job_config=job_cfg,
    db_config=db_cfg,
    verbose=cfg.verbose,
)
evo_runner.run()
```

--------------------------------

### Launching Shinka with Variant in Bash

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/configuration.md

This bash command launches Shinka using a custom variant file for experiment execution. It depends on the shinka_launch script and configured conda environment. Inputs: Variant name. Outputs: Starts the evolutionary process. Limitations: Assumes local cluster; adjust for remote setups.

```bash
shinka_launch variant=my_custom_variant
```

--------------------------------

### Configure and Run Evolution Experiment

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

Sets up and executes an evolutionary experiment using specified configuration arguments and keyword arguments. Requires the shinka library and appropriate dependencies. Takes launcher arguments and keyword arguments as inputs. Outputs are the experiment results stored in a database.

```python
launcher_args = [
    "variant=novelty_generator_example",
    "database=island_small",
    "evolution=small_budget",
    "evo_config.num_generations=10",
]

launcher_kwargs = {
    "evo_config.llm_models": ["gpt-5-mini"],
    "evaluate_function.llm_judge_names": [
        "bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0"
    ],
}

if os.getcwd() != str(repo_root):
    os.chdir(repo_root)
    print("changed working dir to:", repo_root)

job_cfg, db_cfg, evo_cfg, cfg = build_cfgs_from_python(
    *launcher_args, **launcher_kwargs
)
```

```python
evo_runner = EvolutionRunner(
    evo_config=evo_cfg,
    job_config=job_cfg,
    db_config=db_cfg,
    verbose=cfg.verbose,
)
evo_runner.run()
```

--------------------------------

### Agent Design Variant Configuration in YAML

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/configuration.md

This YAML snippet sets up an agent design example with medium-scale island database and evolution budget on local cluster, overriding generation count. It relies on Hydra for composition. Inputs include custom evo_config; outputs integrated setup. Limitations: Medium budget suits quick tests; increase for deeper exploration.

```yaml
# configs/variant/agent_design_example.yaml
 defaults:
  - override /database@_global_: island_medium
  - override /evolution@_global_: medium_budget
  - override /task@_global_: agent_design
  - override /cluster@_global_: local
  - _self_

 evo_config:
  num_generations: 15

 variant_suffix: "_agent_example"
```

--------------------------------

### Implement Packing Validation Function (Python)

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/getting_started.md

This function checks if an evolved circle packing solution meets constraints like bounds and non-overlaps. Depends on output from run_output (centers, radii, sum). Inputs: run_output tuple; outputs: bool validity and optional error message. Limitations: Custom constraint checks must be implemented; returns False for any violation without partial scoring.

```Python
def validate_packing(run_output):
    """Returns (is_valid: bool, error_msg: str or None)"""
    centers, radii, reported_sum = run_output

    # Check constraints (bounds, overlaps, etc.)
    if constraint_violated:
        return False, "Specific error description"

    return True, None  # Valid solution
```

--------------------------------

### Run Circle Packing Evolution Experiment in Python

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

Changes to the circle packing directory if necessary, initializes and runs the EvolutionRunner with the provided configs. Requires the configurations from the setup snippet and a local environment with necessary dependencies. Outputs runtime duration and experiment results, limited to local execution without parallel processing.

```python
circle_packing_path = repo_root / "examples" / "circle_packing"
if os.getcwd() != str(circle_packing_path):
    os.chdir(circle_packing_path)
    print("changed working dir to:", circle_packing_path)

runner = EvolutionRunner(
    evo_config=evo_config,
    job_config=job_config,
    db_config=db_config,
    verbose=True,
)

tic = perf_counter()
runner.run()
toc = perf_counter()

print("completed in", round(toc - tic, 2), "s")
```

--------------------------------

### Launching WebUI with Bash

Source: https://github.com/sakanaai/shinkaevolve/blob/main/README.md

Bash commands for starting the interactive WebUI to monitor evolution experiments in real-time. Launches the visualizer on a specified port and optionally opens it automatically. Inputs are port number and open flag; outputs a running web interface. Requires the experiment to be running separately; depends on shinka_visualize script availability.

```bash
# Start your evolution experiment
shinka_launch variant=circle_packing_example

# In another terminal, launch the WebUI
shinka_visualize --port 8888 --open
```

--------------------------------

### Configure Evolution Settings for Circle Packing in Python

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

Initializes system message, selects available LLM and embedding models based on environment keys, and defines configurations for evolution, database, and job settings. Requires API keys for external services like OpenAI or Gemini as environment variables. Outputs configured objects and prints selections, with limitations on relying on fallback models if keys are missing.

```python
# default circle packing message - can be customized to your liking!
search_task_sys_msg = (
    "You are an expert mathematician specializing in circle packing problems "
    "and computational geometry. The best known result for the sum of radii "
    "when packing 26 circles in a unit square is 2.635.\n\n"
    "Key directions to explore:\n"
    "1. The optimal arrangement likely involves variable-sized circles\n"
    "2. A pure hexagonal arrangement may not be optimal due to edge effects\n"
    "3. The densest known circle packings often use a hybrid approach\n"
    "4. The optimization routine is critically important - simple physics-"
    "based models with carefully tuned parameters\n"
    "5. Consider strategic placement of circles at square corners and edges\n"
    "6. Place larger circles near the center and smaller near the edges\n"
    "7. Math literature suggests special arrangements for specific n\n"
    "8. You can use scipy.optimize to refine radii given fixed centers and "
    "constraints\n\n"
    "Be creative and try to find a new solution."
)

# pick llms based on available keys
llm_models = []
if os.getenv("GEMINI_API_KEY"):
    llm_models.append("gemini-2.5-flash")
if os.getenv("OPENAI_API_KEY"):
    llm_models.append("gpt-5-mini")
if os.getenv("ANTHROPIC_API_KEY"):
    llm_models.append("claude-3-7-sonnet")
elif os.getenv("AWS_ACCESS_KEY_ID") and os.getenv("AWS_REGION"):
    llm_models.append("bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0")
if not llm_models:
    llm_models = ["gpt-5-mini"]  # fallback if no keys detected

# pick embedding model based on available keys
embedding_model_name = ""
if os.getenv("GEMINI_API_KEY"):
    embedding_model_name = "gemini-embedding-001"
elif os.getenv("OPENAI_API_KEY"):
    embedding_model_name = "text-embedding-3-small"
else:
    embedding_model_name = "text-embedding-3-small"
print(f"✅ Embedding model selected: {embedding_model_name}")


# unique experiment directory
timestamp = dt.datetime.now().strftime("%Y%m%d_%H%M%S")
run_tag = f"{timestamp}_weighted_fast"

evo_config = EvolutionConfig(
    task_sys_msg=search_task_sys_msg,
    # use all three mutation patch types and set prob for all
    patch_types=["diff", "full", "cross"],
    patch_type_probs=[0.6, 0.3, 0.1],
    # runs for 20 generations in sequence
    num_generations=20,
    max_parallel_jobs=1,  # only one job at a time
    max_patch_resamples=3,  # resample 3 times if patch fails
    max_patch_attempts=3,  # try 3 times to fix patch via reflection
    # runs locally using the local environment (no loading of conda/docker)
    job_type="local",
    language="python",
    # set LLMs for ensemble
    llm_models=llm_models,
    llm_kwargs=dict(
        temperatures=[0.0, 0.5],  # uniform temperature sampling
        max_tokens=16384,
    ),
    # no meta scratchpad
    meta_rec_interval=None,  # e.g. every 5 generations
    meta_llm_models=None,  # e.g. ["gpt-4.1"]
    meta_llm_kwargs={},  # same as above
    # Set path to initial program relative to repo root
    init_program_path="initial.py",
    results_dir=f"results/circle_packing/{run_tag}",
    # each mutation has three chances of providing a novel solution
    max_novelty_attempts=3,
    # ensemble llm selection among candidates based on past performance
    llm_dynamic_selection=None,  # e.g. "ucb1"
    # set embedding model
    embedding_model=embedding_model_name,
)

db_config = DatabaseConfig(
    db_path="evolution_db.sqlite",
    num_islands=2,
    archive_size=20,
    elite_selection_ratio=0.3,
    num_archive_inspirations=4,
    num_top_k_inspirations=2,
    migration_interval=10,
    migration_rate=0.1,
    island_elitism=True,
    enforce_island_separation=True,
    parent_selection_strategy="weighted",
    parent_selection_lambda=10.0,
    
)

job_config = LocalJobConfig(eval_program_path="evaluate.py")

print("llm_models:", llm_models)
print("embedding_model:", embedding_model_name)
print("results_dir:", evo_config.results_dir)
```

--------------------------------

### GET /api/islands

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Retrieves information about islands in multi-island experiments. This includes status, population, and performance data for each island. Essential for understanding distributed evolution dynamics.

```APIDOC
## GET /api/islands

### Description
Retrieves information about islands in multi-island experiments.

### Method
GET

### Endpoint
/api/islands

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
(Empty body for GET request)

### Response
#### Success Response (200)
- **islands** (array) - List of island objects

#### Response Example
{
  "islands": [
    {"id": 1, "population": 100}
  ]
}
```

--------------------------------

### GET /api/solutions/{id}

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Retrieves detailed information about a specific solution by its ID. This includes code, fitness scores, and metadata. Useful for analyzing individual evolved solutions in depth.

```APIDOC
## GET /api/solutions/{id}

### Description
Retrieves detailed information about a specific solution by its ID.

### Method
GET

### Endpoint
/api/solutions/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the solution

#### Query Parameters
- None

#### Request Body
- None

### Request Example
(Empty body for GET request)

### Response
#### Success Response (200)
- **solution** (object) - Detailed solution data

#### Response Example
{
  "solution": {
    "id": 1,
    "code": "sample code",
    "fitness": 0.95
  }
}
```

--------------------------------

### GET /api/metrics

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Provides performance metrics for the evolution experiment. This endpoint aggregates key statistics such as average fitness, diversity measures, and convergence indicators. Ideal for monitoring overall experiment progress.

```APIDOC
## GET /api/metrics

### Description
Provides performance metrics for the evolution experiment.

### Method
GET

### Endpoint
/api/metrics

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
(Empty body for GET request)

### Response
#### Success Response (200)
- **metrics** (object) - Key performance metrics

#### Response Example
{
  "metrics": {
    "average_fitness": 0.8,
    "diversity": 0.7
  }
}
```

--------------------------------

### Circle Packing Variant Configuration in YAML

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/configuration.md

This YAML file configures a circle packing example using Hydra by overriding defaults for database, evolution, task, and cluster settings. It depends on existing config groups like island_large and large_budget. Inputs are hierarchical defaults; outputs a composed configuration for local execution. Limitations: Tailored for example use; adjust for production scale.

```yaml
# configs/variant/circle_packing_example.yaml
 defaults:
  - override /database@_global_: island_large
  - override /evolution@_global_: large_budget
  - override /task@_global_: circle_packing
  - override /cluster@_global_: local
  - _self_

 variant_suffix: "_example"
```

--------------------------------

### GET /api/generations

Source: https://github.com/sakanaai/shinkaevolve/blob/main/docs/webui.md

Retrieves a list of all generations from the evolution database. This endpoint is useful for browsing the overall progression of the experiment and selecting specific generations for further analysis. It supports filtering and sorting options in advanced implementations.

```APIDOC
## GET /api/generations

### Description
Retrieves a list of all generations from the evolution database.

### Method
GET

### Endpoint
/api/generations

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
(Empty body for GET request)

### Response
#### Success Response (200)
- **generations** (array) - List of generation objects

#### Response Example
{
  "generations": [
    {"id": 1, "generation_number": 1}
  ]
}
```

--------------------------------

### Load and Test Best Program - Python

Source: https://github.com/sakanaai/shinkaevolve/blob/main/examples/shinka_tutorial.ipynb

Dynamically loads the best program module from a file path and executes a test experiment. Uses importlib utilities for module loading. Inputs: Test inputs list (e.g., [1, 2, 3]). Outputs: Novel outputs from the experiment. Requires the loaded module to have a run_experiment function; may raise ImportError if module cannot be loaded.

```python
console = Console()

program_path = results_root / "best/main.py"
spec = importlib.util.spec_from_file_location("program", program_path)
if spec is None or spec.loader is None:
    raise ImportError(f"Could not load module at {program_path}")

module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)

test_inputs = [1, 2, 3]
novel_outputs = module.run_experiment(test_inputs)
```