GigaEvo

Evolutionary algorithm that uses Large Language Models (LLMs) to automatically improve programs through iterative mutation and selection.

Demo

Getting Started

• Quick Start - Get running in 5 minutes
• Architecture Guide - Understand the system design

Documentation

• DAG System - Comprehensive guide to GigaEvo's execution engine
• Evolution Strategies - MAP-Elites and multi-island evolution system
• Tools - Helper utilities for analysis, debugging, and problem scaffolding
• Usage Guide - Detailed usage instructions
• Changelog - Version history and changes
• Contributing - Guidelines for contributors

Quick Start

1. Install Dependencies

Requirements: Python 3.12+

2. Set up Environment

Create a

3. Start Redis

4. Run Evolution

That's it! Evolution will start and logs will be saved to

What Happens

1. Loads initial programs from
   problems/heilbron/
2. Mutates programs using LLMs (GPT, Claude, Gemini, etc.)
3. Evaluates fitness by running the programs
4. Selects best solutions using MAP-Elites algorithm
5. Repeats for multiple generations

Customization

Use a Different Experiment

Change Settings

Configuration

GigaEvo uses a modular configuration system based on Hydra. All configuration is in

Top-Level Configuration

• experiment/
  - Complete experiment templates (start here!)
  • base.yaml
    - Simple single-island evolution (default)
  • full_featured.yaml
    - Multi-island + multi-LLM exploration
  • multi_island_complexity.yaml
    - Two islands: performance + simplicity
  • multi_llm_exploration.yaml
    - Multiple LLMs for diverse mutations

Component Configurations

• algorithm/
  - Evolution algorithms
  • single_island.yaml
    - Standard MAP-Elites
  • multi_island.yaml
    - Multiple independent populations with migration

• llm/
  - Language model setups
  • single.yaml
    - One LLM for all mutations
  • heterogeneous.yaml
    - Multiple LLMs (GPT, Claude, Gemini, etc.) for diverse mutations

• pipeline/
  - DAG execution pipelines
  • auto.yaml
    - Automatically selects pipeline (standard or contextual) based on problem
  • standard.yaml
    - Basic validation → execution → metrics
  • with_context.yaml
    - Includes contextual information extraction
  • custom.yaml
    - Template for custom pipelines

• constants/
  - Tunable parameters grouped by domain
  • evolution.yaml
    - Generation limits, mutation rates, selection pressure
  • llm.yaml
    - Temperature, max tokens, retry logic
  • islands.yaml
    - Island sizes, migration frequency, diversity settings
  • pipeline.yaml
    - Stage timeouts, parallelization settings
  • redis.yaml
    - Connection settings, key patterns
  • logging.yaml
    - Log levels, output formats
  • runner.yaml
    - DAG execution settings
  • endpoints.yaml
    - API endpoint defaults

Supporting Configurations

• loader/
  - Program loading strategies
  • directory.yaml
    - Load initial programs from filesystem
  • redis_selection.yaml
    - Load from existing Redis archive

• logging/
  - Logging backends
  • tensorboard.yaml
    - TensorBoard integration
  • wandb.yaml
    - Weights & Biases tracking

• metrics/
  - Metric computation
  • default.yaml
    - Basic fitness metrics
  • code_complexity.yaml
    - Includes cyclomatic complexity, LOC, etc.

• redis/
  - Redis storage backend

• runner/
  - DAG runner configuration

• evolution/
  - Core evolution engine settings

Configuration Overrides

Override any setting via command line:

See individual YAML files for detailed documentation on each component.

Output

Results are saved to

• Logs:
  evolution_YYYYMMDD_HHMMSS.log
• Programs: Stored in Redis for fast access
• Metrics: TensorBoard logs (if enabled)

Troubleshooting

Redis Database Not Empty

If you see:

ERROR: Redis database is not empty!

Flush the database manually:

Or use a different database number:

LLM Connection Issues

Check your API key in

Verify OpenRouter is accessible:

Architecture

┌─────────────┐
│   Problem   │  Define task, initial programs, metrics
└──────┬──────┘
       │
       v
┌─────────────┐
│  Evolution  │  MAP-Elites algorithm
│   Engine    │  Selects parents, generates mutations
└──────┬──────┘
       │
       v
┌─────────────┐
│     LLM     │  Generates code mutations
│   Wrapper   │  (GPT, Claude, Gemini, etc.)
└──────┬──────┘
       │
       v
┌─────────────┐
│  Evaluator  │  Runs programs, computes fitness
│ (DAG Runner)│  Validates solutions
└──────┬──────┘
       │
       v
┌─────────────┐
│   Storage   │  Redis for fast program access
│   (Redis)   │  Maintains archive of solutions
└─────────────┘

Key Concepts

• MAP-Elites: Algorithm that maintains diverse solutions across behavior dimensions
• Islands: Independent populations that can exchange solutions (migration)
• DAG Pipeline: Stages for validation, execution, complexity analysis, etc.
• Behavior Space: Multi-dimensional grid dividing solutions by characteristics

Advanced Usage

Generate Problem with Wizard

Create problem scaffolding from YAML configuration:

See

Create Your Own Problem Manually

1. Create directory in

   problems/
   :

   problems/my_problem/
     - validate.py           # Fitness evaluation function
     - metrics.yaml          # Metrics specification
     - task_description.txt  # Problem description
     - initial_programs/     # Directory with initial programs
       - strategy1.py        # Each contains entrypoint() function
       - strategy2.py
     - helper.py             # Optional: utility functions
     - context.py            # Optional: runtime context builder
   

2. Run:

See

Custom Experiment

Copy an existing experiment and modify:

Tools

GigaEvo includes utilities for analysis and visualization:

• tools/redis2pd.py
  - Export evolution data to CSV
• tools/comparison.py
  - Compare multiple runs with plots
• tools/dag_builder/
  - Visual DAG pipeline designer
• tools/wizard/
  - Interactive problem setup

See

License

MIT License - see LICENSE file for details.

Citation

If you use GigaEvo in your research, please cite: