codevolve 1.0.6
A Python Library for code optimization
License: Apache-2.0
Requires Python: >=3.9

# CodeEvolve

CodeEvolve is an advanced evolutionary optimization framework that automatically improves code quality and performance using Large Language Models (LLMs) and evolutionary algorithms. It supports both Salesforce Apex and Java code optimization through intelligent program evolution.

## Overview

CodeEvolve implements two powerful optimization algorithms:
- **Evolution Algorithm**: Uses genetic programming concepts to evolve code through selection, mutation, and crossover (based on OpenEvolve)
- **Monte Carlo Tree Search (MCTS)**: Employs tree search with LLM guidance for systematic code exploration

### Key Features

- **Multi-language Support**: Optimizes both Apex and Java codebases
- **LLM-driven Evolution**: Leverages GPT-4 and other models for intelligent code generation
- **Performance-focused**: Optimizes for execution speed, memory efficiency, and code quality
- **Configurable**: Extensive YAML configuration for fine-tuning optimization parameters
- **Checkpoint/Resume**: Save and restore optimization progress
- **Evaluation Framework**: Built-in testing and performance measurement

### Use Cases

- **Performance Optimization**: Improve algorithm efficiency and reduce execution time
- **Code Quality Enhancement**: Refactor code for better maintainability and readability  
- **Memory Optimization**: Reduce memory footprint and prevent memory leaks
- **Best Practice Compliance**: Ensure code follows language-specific best practices

## Installation

### Prerequisites
- Python 3.9 or higher

For Apex development:
- Salesforce CLI (sfdx)
- Valid Salesforce org credentials

For Java development:
- Java Development Kit (JDK) 11 or higher
- Bazel build tool
- Core Development: https://git.soma.salesforce.com/pages/dx/docs/core/paved-path/

### Install from Source

1. Clone the repository:
```bash
git clone https://git.soma.salesforce.com/wenzhuo-yang/CodeEvolve
cd CodeEvolve
```

2. Create a virtual environment (recommended):
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
```

4. Set up environment variables:
```bash
# Create .env file with your API keys
cp .env.example .env
# Edit .env with your OpenAI API key and other credentials
```

## Usage

### Basic Usage

Run CodeEvolve with the basic command:
```bash
PYTHONPATH=. python codevolve/run.py <initial_program> <evaluation_file> [options]
```

### Common Examples

#### Apex Code Optimization
```bash
# Basic Apex optimization
PYTHONPATH=. python codevolve/run.py applications/apex/samples/1/initial_program.apex applications/apex/evaluator.py \
  --config applications/apex/samples/1/config.yaml
```

#### Java Code Optimization
```bash
# Basic Java optimization
PYTHONPATH=. python codevolve/run.py applications/java/samples/1/initial_program.java applications/java/evaluator.py \
  --config applications/java/samples/1/config.yaml

# Specify algorithm (evolution or mcts)
PYTHONPATH=. python codevolve/run.py applications/java/samples/1/initial_program.java applications/java/evaluator.py \
  --config applications/java/samples/1/config.yaml --algorithm mcts
```

### Quick Start Examples

#### Run Apex Sample
```bash
bash applications/apex/samples/1/run_apex_evolve.sh    # Optimize code
bash applications/apex/samples/1/run_visualization.sh  # View results
```

#### Run Java Sample
```bash
bash applications/java/samples/1/run_optimization.sh   # Optimize code
bash applications/java/samples/1/run_visualization.sh  # View results
```

## Code Block Labeling

To guide CodeEvolve's optimization focus, you can mark specific sections of your code using special block markers. This allows you to specify which parts of the code should be the primary target for evolutionary optimization.

### EVOLVE-BLOCK Markers

Use the following markers to define evolution target blocks in your code:

```java
// EVOLVE-BLOCK-START
// Code that should be optimized goes here
public void targetMethod() {
    // This method will be the focus of optimization
    for (int i = 0; i < items.size(); i++) {
        processItem(items.get(i));
    }
}
// EVOLVE-BLOCK-END
```

### Usage Guidelines

- **Single Target**: Use one EVOLVE-BLOCK per file to maintain focus
- **Method-Level**: Typically wrap individual methods or small code sections
- **Clear Boundaries**: Ensure the block contains complete, compilable code units
- **Context Preservation**: Code outside the block provides necessary context but won't be modified

## Configuration Guide

This guide explains how to write configuration files for CodeEvolve applications. Configuration files use YAML format and control all aspects of the evolutionary optimization process.

### Basic Structure

A typical CodeEvolve configuration file contains the following main sections:

```yaml
# Basic settings
max_iterations: 20
checkpoint_interval: 1
log_level: "INFO"

# LLM configuration
llm:
  # Model settings...

# Prompt configuration  
prompt:
  # Prompt templates and settings...

# Database configuration
database:
  # Population and evolution settings...

# Evaluator configuration
evaluator:
  # Evaluation settings and context...

# Evolution settings
diff_based_evolution: false
allow_full_rewrites: true
max_code_length: 30000
```

### Configuration Sections

#### 1. Basic Settings

```yaml
max_iterations: 30              # Maximum number of optimization iterations
checkpoint_interval: 2          # Save checkpoint every N iterations  
log_level: "INFO"               # Logging level: DEBUG, INFO, WARN, ERROR
```

#### 2. LLM Configuration

Controls the language models used for code generation and optimization:

```yaml
llm:
  primary_model: "gpt-4o"                   # Primary LLM model
  primary_model_weight: 0.8                 # Weight for ensemble (0.0-1.0)
  secondary_model: "gpt-4.1"                # Secondary model (optional)
  secondary_model_weight: 0.2               # Secondary model weight
  api_base: "https://api.openai.com/v1"     # API endpoint
  temperature: 0.5                          # Creativity (0.0-2.0, lower = more focused)
  top_p: 0.95                               # Nucleus sampling (0.0-1.0)
  max_tokens: 16384                         # Maximum tokens per request
  timeout: 120                              # Request timeout in seconds
```

**Key Parameters:**
- **temperature**: Lower values (0.1-0.4) for consistent optimizations, higher (0.6-1.0) for creative exploration
- **primary_model_weight**: Higher weight (0.8-0.9) on primary model for consistency
- **max_tokens**: Adjust based on code complexity (4096-16384 for Java/Apex)

#### 3. Prompt Configuration

Defines the system prompt and template variations:

```yaml
prompt:
  system_message: |
    You are an expert Java optimization agent specializing in Salesforce Core App development...
    
    ## Core Optimization Objectives
    1. **Execution Speed**: Optimize algorithmic complexity...
    2. **Memory Efficiency**: Minimize object allocation...
    
    Now, optimize the following Java code:
    
  num_top_programs: 3              # Number of top programs to consider
  num_diverse_programs: 5          # Number of diverse programs for selection
  use_template_stochasticity: true # Enable prompt variations
  
  template_variations:
    improvement_suggestion:
      - "Here are specific performance optimizations for this Java code:"
      - "To enhance this Salesforce Core App implementation:"
      - "Apply these enterprise-grade performance improvements:"
      
  include_artifacts: true         # Include evaluation artifacts in prompts
  max_artifact_bytes: 4096        # Limit artifact size in prompts
  artifact_security_filter: true  # Filter sensitive information
```

**System Message Guidelines:**
- Include specific optimization objectives for your domain
- Provide clear constraints and requirements
- Use language-specific best practices
- Include output format requirements

#### 4. Database Configuration

Controls population management and evolutionary algorithms:

```yaml
database:
  population_size: 40              # Size of program population
  archive_size: 15                 # Archive size for best programs
  num_islands: 3                   # Number of evolution islands
  exploitation_ratio: 0.8          # Focus on best programs (0.0-1.0)
  
  # Migration settings
  migration_interval: 4            # Migrate every N iterations
  migration_rate: 0.15            # Fraction of population to migrate
  
  # Feature dimensions for diversity
  feature_dimensions:
    - "code_efficiency_score"      # Code efficiency metric
    - "code_quality_score"         # Code quality metric
    - "test_success_ratio"         # Test pass rate
    - "memory_efficiency"          # Memory usage optimization
    
  feature_bins: 8                  # Granularity for diversity mapping
  
  critical_features:
    - "build_success"              # Must compile/build successfully
```

**Key Parameters:**
- **population_size**: 30-50 for complex code, 15-30 for simple utilities.
- **exploitation_ratio**: Higher (0.7-0.8) for performance focus, lower (0.5-0.6) for exploration.
- **feature_dimensions**: Include metrics relevant to your optimization goals.
- **critical_features**: Features that programs must satisfy to be considered valid (e.g., "build_success = 1.0", "test_pass_score = 1.0"). Programs failing critical features are filtered out during evolution.

#### 5. Evaluator Configuration

Defines how programs are evaluated and tested:

```yaml
evaluator:
  timeout: 300                     # Evaluation timeout (seconds)
  max_retries: 3                   # Retry failed evaluations
  cascade_evaluation: true         # Use cascaded evaluation
  cascade_thresholds: [0.4, 0.7]   # Quality thresholds for cascade
  parallel_evaluations: 1          # Number of parallel evaluations
  use_llm_feedback: false          # Enable LLM-based feedback
  enable_artifacts: true           # Store evaluation artifacts
  
  context:
    project_folder: "/path/to/project"     # Project root directory
    module_name: "my-module"               # Module being optimized
    code_file: "/path/to/code/file.java or java/src/code/file.java"   # Target code file
```

**Context Parameters:**
- **project_folder**: Root directory of your project
- **module_name**: Specific module or component name
- **code_file**: Path to the file being optimized. If the path begins with "java/src", the project folder and module name are prefixed to it.

#### 6. Evolution Settings

Controls the evolutionary optimization process:

```yaml
# Evolution behavior
diff_based_evolution: false              # Use diff-based changes
allow_full_rewrites: true               # Allow complete code rewrites
max_code_length: 30000                  # Maximum code length limit
```

### Example: Complete Configuration

See `applications/apex/samples/1/config.yaml` for a complete working example optimized for Apex code optimization.

See `applications/java/samples/1/config.yaml` for a complete working example optimized for Java code optimization in Salesforce Core App development.