🧪 Mergenetic: Evolutionary Model Merging for LLMs

mergenetic is a flexible library for merging large language models (LLMs) via evolutionary optimization. It frames model merging as a black-box optimization problem and uses techniques like genetic algorithms and smart performance estimators to search for optimal weight combinations — enabling high-performance merges, even on consumer hardware.

✨ Why Mergenetic?

• State‑of‑the‑art merging techniques – linear soups, SLERP, TIES/DARE, Task Arithmetic and more.
• Hardware‑friendly – search in parameter space, not gradient space; no model must fit in memory twice.
• Modular & hackable – plug‑and‑play problems, searchers, mergers and evaluators.
• Familiar tools under the hood – mergekit for merging, pymoo for optimisation, and lm‑eval‑harness for metrics.

📚 Table of Contents

1. Installation
2. Quickstart
3. Key Concepts
4. Usage Examples
   • Python API
   • Command‑Line Interface
   • Graphical Interface
5. Project Layout
6. Learn More
7. Contributing
8. Citation
9. License

🛠️ Installation

You can install the latest release directly from PyPI:

pip install mergenetic

Or update an existing installation:

pip install --upgrade mergenetic

Another option is to create a conda environment and install it from source:

git clone https://github.com/tommasomncttn/mergenetic.git
cd mergenetic
conda create --name mergenetic python=3.11 -y
conda activate mergenetic
pip install -r requirements.txt
pip install -e .

Heads‑up: some merge methods require bfloat16 support. Make sure your CUDA / ROCm stack is recent enough.

⚡ Quickstart

The fastest way to see Mergenetic in action is the Colab notebook here

🔑 Key Concepts

1. Merging Strategies

2. Evolutionary Algorithms

Mergenetic wraps every single‑ and multi‑objective optimiser in pymoo – GA, DE, CMA‑ES, NSGA‑II/III and many more. Simply import the one you need:

from pymoo.algorithms.soo.genetic_algorithm import GA
algorithm = GA(pop_size=32)

3. Evaluation & Fitness

• Native support for LM‑Eval Harness tasks
• Low‑cost proxies: IRT estimators or random sampling
• Bring‑your‑own metric by writing a single function

🚀 Usage Examples

Python API

from mergenetic.searcher import Searcher
from mergenetic.optimization.predefined_problems import CrossLingualMathProblem
from mergenetic.merging import SlerpMerger
from mergenetic.utils import ConfigLmEval

config = ConfigLmEval(**yaml.load(open("path/to/config.yaml"), Loader=yaml.FullLoader))

merger = SlerpMerger(...)
problem = CrossLingualMathProblem(...)
algorithm = GA(...)
searcher = Searcher(problem, algorithm, config.path_to_store_config, config.n_iter, config.run_id, config.seed)

searcher.search()
searcher.test()

Command‑Line Interface

python -m mergenetic.cli \
  --merge-type single \
  --eval-method lm-eval \
  --models mistral-7b math-7b \
  --task gsm8k-it

An interactive wizard will guide you through the remaining options. See cli/README.md for the full reference.

Graphical Interface

Run the Gradio dashboard locally:

cd gui
pip install -r requirements.txt
python3 gui.py

…and configure experiments with dropdowns – no code required! See gui/README.md for the full details.

🗂️ Project Layout

mergenetic/
├── merging/          # adapters around mergekit strategies
├── optimization/     # pymoo problems for various tasks
├── evaluation/       # LM‑Eval & custom fitness functions
├── estimator/        # fast score predictors (IRT, sampling)
├── searcher/         # evolutionary loop orchestration
└── utils/            # config, logging, GPU helpers, …

Detailed docs for each module live in src/mergenetic/README.md.

📒 Learn More

• 📓 Tutorial notebook: notebooks/Cross_Lingual_Math_Merging.ipynb
• 🎞️ Video walk‑through: YouTube (5 min)
• 🔗 Related repos: mergekit · pymoo · lm‑eval‑harness

🤝 Contributing

Bug reports, feature requests and pull requests are very welcome! Please read CONTRIBUTING.md before you start.

🧠 Citation

@inproceedings{minut-etal-2025-mergenetic,
    title = "Mergenetic: a Simple Evolutionary Model Merging Library",
    author = "Minut, Adrian Robert  and
      Mencattini, Tommaso  and
      Santilli, Andrea  and
      Crisostomi, Donato  and
      Rodol{\`a}, Emanuele",
    editor = "Mishra, Pushkar  and
      Muresan, Smaranda  and
      Yu, Tao",
    booktitle = "Proceedings of the 63rd Annual Meeting of the Association for Computational Linguistics (Volume 3: System Demonstrations)",
    month = jul,
    year = "2025",
    address = "Vienna, Austria",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2025.acl-demo.55/",
    pages = "572--582",
    ISBN = "979-8-89176-253-4"
}

📄 License

Licensed under the Apache 2.0 licence – see the LICENSE file for details.