Evolution

Evolution is the core engine of HezGene. It takes a function, extracts its DNA, spawns mutant variants, evaluates them in a fitness arena, and deploys the winner — all automatically.

How it works

When you run hezgene run, the evolution engine executes a 5-step pipeline for every evolvable function it finds:

1. Scan: Parse the target file and identify functions with more than 2 lines of logic.
2. Extract DNA: Calculate the baseline fitness profile — speed, memory, cyclomatic complexity, Halstead metrics, and line count.
3. Spawn Mutants: Generate N mutant versions using AST transformation strategies (and optionally LLM strategies).
4. Arena Battle: Run each mutant through the 5-Ring Fitness Gauntlet to score correctness, speed, memory, edge-case resilience, and readability.
5. Selection: The tournament manager compares all mutant scores against the original. If a mutant wins, it is deployed to the sandbox (or to your source files with --apply).

Evolution targets

# Evolve an entire directory
hezgene run src/

# Evolve a single file
hezgene run src/utils.py

# Evolve a specific function
hezgene run src/utils.py:calculate_total

# Auto-target the slowest function
hezgene run --target slowest

# Auto-target the buggiest function
hezgene run --target buggiest

Generations

By default, HezGene spawns 5 mutants per function. You can increase this for more thorough optimization:

hezgene run src/ -g 10    # 10 mutant generations

Apply mode

By default, winners are placed in .hezgene/sandbox/. To actually modify your source files:

hezgene run src/utils.py --apply

When --apply is used, HezGene creates a timestamped backup of the original file before overwriting it. You can always roll back:

hezgene rollback src/utils.py