Antibody Fv Generative Model for high accuracy prediction of CDR-H3 Loops

---

This repository provides a local inference workflow for our finetuned antibody language model based on p-IgGen.

The inference script supports:

• De novo generation of full-length paired antibody sequences
• Conditional generation from a provided heavy or light chain
• Prompted generation from an initial sequence
• Optional likelihood-based filtering of outputs
• Optional separation of VH and VL chains in outputs
• Optional reverse generation

---

All scripts for finetune data curation, training, inference and evaluation can be found at psipred/Antibody-design/main/scripts. The diagrams below map the data flow through the fine-tuning data curation and inference/pre-evaluation pipelines, tracing how each script's inputs and outputs connect. Model training and evaluation are omitted as their workflows are comparatively straightforward

Finetune data curation Inference and pre-evaluation

Installation

Prerequisites

• Conda
• Git
• Internet access (for downloading model and dependencies)

1. Create environment

conda create -n piggen_infer python=3.11 pip -y
conda activate piggen_infer

2. Install p-IgGen

pip install git+https://github.com/OliverT1/p-IgGen.git

3. Install required dependencies

pip install torch transformers click

4. Install HMMER (required by ANARCI)

conda install -n piggen_infer -c bioconda hmmer -y

5. Install ANARCI

conda run -n piggen_infer pip install anarci

Note: This inference script imports ANARCI at startup, so ANARCI must be installed even if you are not using --separate_chains.

---

Inference Script

Download the inference script:

wget https://raw.githubusercontent.com/psipred/Antibody-design/main/operations/user_inference.py -O github_inference.py

Or with curl:

curl -o github_inference.py https://raw.githubusercontent.com/psipred/Antibody-design/main/operations/user_inference.py

Usage

Generate sequences with a simple command:

python github_inference.py \
  --n_sequences 10 \
  --output_file output_unconditional.txt \
  --device cpu

Parameters

Input conditioning

Flag	Description
--heavy_chain_file TEXT	File containing heavy chain sequences (one per line)
--light_chain_file TEXT	File containing light chain sequences (one per line)
--initial_sequence TEXT	Initial sequence prompt

For p-IgGen prompted generation, prefix the prompt with 1. Example: --initial_sequence 1QVQLVES...

Sampling

Flag	Description	Default
--n_sequences INTEGER	Number of sequences to generate	1
--top_p FLOAT	Top-p nucleus sampling	0.95
--temp FLOAT	Sampling temperature	1.2
--bottom_n_percent INTEGER	Percentage of lowest-likelihood sequences to discard (only used if n_sequences >= 100)	5

Generation control

Flag	Description
--backwards	Generate sequences in reverse direction
--separate_chains	Output VH and VL separately (requires ANARCI)

Output

Flag	Description
--output_file TEXT	Output file path (required)

Notes

• The model samples next tokens probabilistically instead of always picking the single most likely token, giving diversity across outputs
• Each generation (not including prompt) can add at most 400 new tokens
• bottom_n_percent only applies when n_sequences >= 100
• Some generated samples can be dropped by post-generation validation, so written output count may be lower than --n_sequences
• --heavy_chain_file and --light_chain_file are mutually exclusive
• In prompted mode, --initial_sequence accepts a single prompt string

Generation direction

Sequences are generated by default in the direction VH -> VL (C-term to N-term). Alternatively, they can be generated in reverse from VL -> VH (N-term to C-term) using the --backwards flag. This allows generation given a VH or VL sequence of any length.

Note:

• If --backwards is used with --initial_sequence, the prompt should be provided in reverse, starting from the N-term of the VL chain.
• If --heavy_chain_file or --light_chain_file is used, this inversion is handled automatically, and the VH and VL chains should be provided in the standard direction.

Example use

Unconditional generation:

python github_inference.py \
  --n_sequences 10 \
  --output_file output_unconditional.txt \
  --device cpu

Conditional generation from heavy chains (heavy -> light):

python github_inference.py \
  --heavy_chain_file heavy_chains.txt \
  --n_sequences 5 \
  --top_p 0.95 \
  --temp 1.2 \
  --output_file output_from_heavy.txt \
  --device cpu

Conditional generation from light chains (light -> heavy):

python github_inference.py \
  --light_chain_file light_chains.txt \
  --n_sequences 5 \
  --top_p 0.95 \
  --temp 1.2 \
  --output_file output_from_light.txt \
  --device cpu

Prompted generation from an initial sequence (prefix with 1):

python github_inference.py \
  --initial_sequence 1QVQLVESGGGVVQPGRSLRLSCAASGFTFSSYGMHWVRQAPGKG \
  --n_sequences 20 \
  --top_p 0.9 \
  --temp 1.1 \
  --output_file output_prompted.txt \
  --device cpu

Output format

Default output:

SEQUENCE_1
SEQUENCE_2
SEQUENCE_3

Conditional generation output:

index, generated_sequence

Separate chain output:

VH_SEQUENCE, VL_SEQUENCE

---

Quick Test

python -c "import torch; import transformers; print('Core dependencies OK')"
python -c "from piggen import utils; print('p-IgGen import OK')"
python github_inference.py --help

---

Troubleshooting

ANARCI not found

conda install -n piggen_infer -c bioconda anarci -y
# If that fails:
conda run -n piggen_infer pip install anarci

hmmscan not found

conda install -n piggen_infer -c bioconda hmmer -y

--separate_chains not working

Ensure both ANARCI and HMMER are installed and available in PATH.

Prompted generation returns 0 sequences

Use --initial_sequence with a leading 1 token (for example, --initial_sequence 1QVQLVES...).

---

About

This repository provides local inference for a finetuned version of p-IgGen.

Upstream package: https://github.com/OliverT1/p-IgGen