NbForge

command-line interface hub for nanobody (VHH) structure prediction, based on the work done in: https://www.biorxiv.org/content/10.64898/2026.02.13.705647v1

user friendly webserver available at: https://www-cohsoftware.ch.cam.ac.uk

Compatible with Python 3.12.

Usage

All sequences are passed through ANARCI and trimmed to the VHH domain before prediction. Runs will stop if ANARCI fails or the sequence is not VH/VHH. Predictions are written with AHo residue numbering.

Step-by-step (clean install + single-sequence test):

1. Clone and enter the repo:

git clone https://gitlab.doc.ic.ac.uk/sormanni-lab/nbforge.git
cd nbforge

2. Install into your existing environment (recommended for pipeline integration):

pip install .

3. Optional: create the managed conda environment instead:

# CPU environment
./scripts/create_env.sh

# GPU environment (Linux only)
./scripts/create_env.sh gpu

conda activate nbforge
pip install .

4. Prepare the inference cache (one-time):

nbforge prepare

5. Run a single sequence:

nbforge --sequence "QVKLEESGGGLVQPGGSLRLSCAGTGWTLEFYAIAWYRQAPGKERELVSCISSSSESNTYEDSVKGRFAMSRDKSRNTAWLQMNNLKPADSGVYYCAALPNMNCIREVMQYVDEWGQGTPVTVSS" \
  --VHH_name TEST1 --outdir ./predictions

NbFrame scoring (optional)

Based on the NbFrame github: https://github.com/Mateusz-Jaskolowski/NbFrame/tree/main

Add --nbframe to compute two extra scores, written into the summary CSV:

• nbframe_seq (sequence-based)
• nbframe_struct (structure-based)

OpenMM minimization (default)

By default, NbForge runs an ImmuneBuilder2-style restrained OpenMM energy minimization. To skip minimization, pass --no-minimize.

If OpenMM minimization dependencies are unavailable in your environment, either:

• install OpenMM + PDBFixer (recommended via conda-forge): conda install -c conda-forge openmm pdbfixer 'setuptools<81'
• or run inference with --no-minimize.

Summary CSV naming:

• Single input: <VHH_name>_summary.csv
• FASTA/CSV input: <input_file_stem>_summary.csv

If ANARCI is missing, install it manually: conda install -c bioconda anarci.

If you see SSH/OpenSSL errors when pulling (e.g. "Fatal: could not read from remote repository"), force git to use the system SSH:

./scripts/fix_ssh.sh

CPU / GPU inference

nbforge --sequence "QVKLEESGGGLVQPGGSLRLSCAGTGWTLEFYAIAWYRQAPGKERELVSCISSSSESNTYEDSVKGRFAMSRDKSRNTAWLQMNNLKPADSGVYYCAALPNMNCIREVMQYVDEWGQGTPVTVSS" \
  --VHH_name TEST1 --outdir ./predictions

CPU is the default; you can also force CPU explicitly with --cpu. GPU inference is opt-in via --gpu.

GPU inference (CUDA):

nbforge --sequence "QVQLVESGGGLVQAGGSLRLSCAAS..." --VHH_name NB001 \
  --outdir ./predictions --gpu 0

Notes:

• --cpu and --gpu are mutually exclusive.
• --gpu accepts either a GPU index (e.g. 0) or a full torch device string (e.g. cuda:0).
• For the managed conda setup, GPU inference requires ./scripts/create_env.sh gpu on Linux.
• For an existing environment, GPU inference requires a CUDA-enabled PyTorch install.
• If CUDA isn't available, --gpu will raise an error.

Multiple inference (FASTA / CSV / TSV)

CSV/TSV (required columns: VHH_name, sequence):

nbforge --input sequences.csv --outdir ./predictions

For faster CPU throughput on many sequences, you can parallelise across processes:

nbforge --input sequences.csv --outdir ./predictions --cpu-workers 8

FASTA:

nbforge --input sequences.fasta --outdir ./predictions

Contact

Please contact ma986@cam.ac.uk to report issues or for any questions.