BAGEL is a model-agnostic, modular, fully customizable Python framework for programmable protein design.

The package formalizes the protein design task as an optimization (sampling) over an energy landscape.

The BAGEL package is made up of several components that need to be specified to form a protein engineering task:

For more details, consult the available pre-print.

The easiest way to install BAGEL is through PyPI:

pip install biobagel

Optional Extras:

• For local protein model execution (requires GPU):

pip install biobagel[local]

• For development (testing, linting, documentation):

pip install biobagel[dev]

If you want to install from source or contribute to development:

1. Clone the repository:

git clone https://github.com/softnanolab/bagel

2. Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

3. Navigate to the repository:

cd bagel

4. Install the environment:

uv sync

Optional Extras:

• For local protein model execution (requires GPU):

uv sync --extra local

• For development (testing, linting, documentation):

uv sync --extra dev

• For all extras:

uv sync --all-extras

python scripts/script.py

uv run python scripts/script.py

To execute templates reproducibly from the technical report manuscript (within statistical noise due to the nature of Monte Carlo sampling), follow release v0.1.0, also stored on Zenodo . Otherwise, use the most recent biobagel distribution.

One can either run Oracles locally, or remotely.

• use_modal=True: Run Oracles on Modal. Using the boileroom package, running remotely is made seamless and does not require installing any dependencies. However, you need to have credits to use Modal.
• use_modal=False: Run Oracles locally through boileroom. You need a GPU with suitable memory requirements.

To use Modal, one needs to create an account and authenticate through:

    modal token new

You also need to set MODEL_DIR to an accessible folder, where deep learning models will be stored (i.e. cached).

Note on cache location and persistence:

• By default, examples may resolve MODEL_DIR to an XDG-compliant cache directory such as ~/.cache/bagel/models (or the path in $XDG_CACHE_HOME). This directory is user-writable and persists across runs.
• The cache is not automatically cleaned by the application. If you wish to reclaim disk space, remove models manually (e.g., rm -rf ~/.cache/bagel/models) or configure your own housekeeping policy. Advanced users on Linux can use systemd-tmpfiles rules per their environment.

A prototyping, but unscalable alterantive is to run BAGEL in Google Colab, having an access to a T4 processing unit for free. See this notebook, which includes the installation, and the template script for simple binder.

Templates and example applications from the manuscript are included as ready-to-run Python scripts.

For development setup, testing, and contribution guidelines, see Development Guide.

@article{lala2025bagel,
        author = {L{\'a}la, Jakub and Al-Saffar, Ayham and Angioletti-Uberti, Stefano},
        title = {BAGEL: Protein Engineering via Exploration of an Energy Landscape},
        journal = {bioRxiv},
        year = {2025},
        doi = {10.1101/2025.07.05.663138},
        url = {https://www.biorxiv.org/content/early/2025/07/08/2025.07.05.663138},
        note = {Preprint}
}

BAGEL's development was lead by Jakub Lála, Ayham Al-Saffar, and Dr Stefano Angioletti-Uberti at Imperial College London. We thank Shanil Panara, Dr Daniele Visco, Arnav Cheruku, and Harsh Agrawal for helpful discussions. We also thank Hie et. al 2022, whose work inspired the creation of this package.