:safety_vest: SAFE

Sequential Attachment-based Fragment Embedding (SAFE) is a novel molecular line notation that represents molecules as an unordered sequence of fragment blocks to improve molecule design using generative models.

Paper | Docs | 🤗 Model | 🤗 Training Dataset

Overview of SAFE

SAFE is the deep learning molecular representation. It's an encoding leveraging a peculiarity in the decoding schemes of SMILES, to allow representation of molecules as a contiguous sequence of connected fragments. SAFE strings are valid SMILES strings, and thus are able to preserve the same amount of information. The intuitive representation of molecules as an ordered sequence of connected fragments greatly simplifies the following tasks often encountered in molecular design:

• de novo design
• superstructure generation
• scaffold decoration
• motif extension
• linker generation
• scaffold morphing.

The construction of a SAFE strings requires defining a molecular fragmentation algorithm. By default, we use [BRICS], but any other fragmentation algorithm can be used. The image below illustrates the process of building a SAFE string. The resulting string is a valid SMILES that can be read by datamol or RDKit.

News 🚀

💥 2026/09/03 💥

1. SAFE 0.2.0 release. A maintenance-focused release. It preserves E/Z and atom stereochemistry across fragmentation, makes strict and permissive decoding behaviour explicit, supports extended ring closures, and updates SAFE-GPT to Transformers 5 without changing the established seeded generation paths. The core notation package is lightweight, while model, training, visualization and Weights & Biases support are independent extras. Sampling gains an optional try_hard quality pass and deterministic handling of linker and pattern constraints. See the complete changelog and the migration guide.

💥 2024/01/15 💥

1. @IanAWatson has a C++ implementation of SAFE in LillyMol that is quite fast and use a custom fragmentation algorithm. Follow the installation instruction on the repo and checkout the docs of the CLI here: docs/Molecule_Tools/SAFE.md

Installation

SAFE 0.2.0 supports Python 3.11 through 3.14.

uv add safe-mol          # or: pip install safe-mol
mamba install -c conda-forge safe-mol

The base install covers the notation core (safe.encode, safe.decode, safe.split) and molecule visualization, and needs no PyTorch — so it runs anywhere, including Mac Intel. The model stack is a single optional extra:

uv add "safe-mol[model]"        # or: pip install "safe-mol[model]"

Installing the extra always includes the base, so safe-mol[model] gives you the core, visualization and the full model stack. Model APIs keep their top-level imports but load their dependencies only when used. The model extra requires PyTorch 2.5+; official Mac Intel wheels stop at 2.2, so use Linux, Windows or Apple Silicon for that stack. It uses Transformers 5, and RDKit 2026.03 is excluded because of an upstream stereochemistry regression (RDKit 2024.09 through 2025.09 are covered by CI). See the migration guide for details.

For GPU workloads, install the PyTorch build matching your CUDA driver before installing SAFE. You can verify the resulting environment with:

import torch

print(torch.cuda.is_available())

Datasets and Models

Usage

Please refer to the documentation, which contains tutorials for getting started with safe and detailed descriptions of the functions provided, as well as an example of how to get started with SAFE-GPT.

API

We summarize some key functions provided by the safe package below.

Examples

Translation between SAFE and SMILES representations

import safe

ibuprofen = "CC(Cc1ccc(cc1)C(C(=O)O)C)C"

# SMILES -> SAFE -> SMILES translation
try:
    ibuprofen_sf = safe.encode(ibuprofen)  # c12ccc3cc1.C3(C)C(=O)O.CC(C)C2
    ibuprofen_smi = safe.decode(ibuprofen_sf, canonical=True)  # CC(C)Cc1ccc(C(C)C(=O)O)cc1
except safe.SAFEEncodeError:
    pass
except safe.SAFEDecodeError:
    pass

ibuprofen_tokens = list(safe.split(ibuprofen_sf))

Training/Finetuning a (new) model

A command line interface is available to train a new model, please run safe-train --help. You can also provide an existing checkpoint to continue training or finetune on you own dataset.

For example:

safe-train --config <path to config> \
    --model-path <path to model> \
    --tokenizer  <path to tokenizer> \
    --dataset <path to dataset> \
    --num_labels 9 \
    --torch_compile True \
    --optim "adamw_torch" \
    --learning_rate 1e-5 \
    --prop_loss_coeff 1e-3 \
    --gradient_accumulation_steps 1 \
    --output_dir "<path to outputdir>" \
    --max_steps 5

References

If you use this repository, please cite the following related paper:

@misc{noutahi2023gotta,
      title={Gotta be SAFE: A New Framework for Molecular Design},
      author={Emmanuel Noutahi and Cristian Gabellini and Michael Craig and Jonathan S. C Lim and Prudencio Tossou},
      year={2023},
      eprint={2310.10773},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

License

The training dataset is licensed under CC BY 4.0. See DATA_LICENSE for details. This code base is licensed under the Apache-2.0 license. See LICENSE for details.

Note that the model weights of SAFE-GPT are exclusively licensed for research purposes (CC BY-NC 4.0).

These licences apply to separate materials. The Python package does not redistribute the model weights.

Development lifecycle

Setup dev environment

uv sync --all-extras

This creates an isolated .venv with the training, visualisation, reporting, test, documentation and development extras. env.yml remains available when a Conda environment is required.

Tests

You can run tests locally with:

uv run python -m pytest -m "not integration"
uv run python -m pytest -m integration --no-cov

The integration command validates the published SAFE-GPT model and executes the maintained tutorials. GitHub Actions runs the same command. Use uv run python -m pytest -m notebook --no-cov when iterating on tutorials only.

Releasing

Release maintainers: see the manual release guide.