biobagel 0.1.8

Protein Engineering via Exploration of an Energy Landscape

BAGEL: Protein Engineering via Exploration of an Energy Landscape

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:

Component	Description	Examples
EnergyTerms	Define specific design constraints as terms in the energy function.	TemplateMatchEnergy, PLDDTEnergy, HydrophobicEnergy
Oracles	Provide information (often via ML models) to compute optimization/sampling metrics. Oracles are typically wrappers around models from boileroom.	ESMFold, ESM-2
Minimizers	Algorithms that sample or optimize sequences to find optima or diverse variants.	Monte Carlo, SimulatedTempering, SimulatedAnnealing
MutationProtocols	Methods for perturbing sequences to generate new candidates.	Canonical, GrandCanonical

For more details, consult the available pre-print.

Installation

From PyPI (Recommended)

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]

From Source

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

Usage

With PyPI Installation

python scripts/script.py

With Source Installation

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.

Oracles

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.

Google Colab

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.

Examples

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

Contributing

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

Citation

@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}
}

Acknowledgments

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.