ablanx
ablanx is a faithful JAX/Flax port of the AbLang2 AbRep encoder. It loads the original AbLang2 weights unchanged and returns per-residue embeddings and per-block attention in a single JAX forward pass, so an antibody sequence prior can sit inside a larger JAX/Flax model.
AbLang2 is the work of the Oxford Protein Informatics Group (OPIG); this repository is a port, not a new model. Provenance and citation are in ATTRIBUTION.md and CITATION.cff.
Why use it
- Drop-in AbLang2 embeddings inside JAX/Flax workflows.
- No PyTorch dependency at inference (weights load from a plain npz).
- Pure JAX forward:
jit/vmap/grad-compatible and composable in a larger model. - Per-block attention returned directly from the same call.
- Numerically verified against the reference implementation (max abs 3.9e-6 across a 30-Fv panel).
Quickstart
Install:
pip install git+https://github.com/fabricagen/ablanx
# from a clone: pip install .
# imports as `ablang_jax`; PyPI (pip install ablanx) is planned.
Embeddings:
import numpy as np, jax.numpy as jnp
from ablang_jax import Ablanx, load_ablanx_params
model = Ablanx()
params = {"params": load_ablanx_params(dict(np.load("ablang2_weights.npz")))} # AbRep weights
tokens = jnp.array([[...]], dtype=jnp.int32) # AbLang2 token ids, shape [B, L]
mask = jnp.ones_like(tokens, dtype=jnp.float32) # 1 = keep, 0 = pad
hidden, attentions = model.apply(params, tokens, mask, return_attn=True)
# hidden: [B, L, 480] per-residue embeddings
# attentions: [12, B, 20, L, L] per-block attention maps
See Weights for the npz.
What it is
AbLang2 is an antibody-specific protein language model. Its encoder (AbRep) is a 12-block pre-norm
transformer: hidden 480, 20 heads, SwiGLU feed-forward, rotary position embeddings, vocab 26,
trained on paired antibody sequences. ablanx re-expresses AbRep in Flax so the original
BSD-3-Clause weights load without change, returning per-residue hidden states and per-block attention
maps in one forward pass.
Differentiability
The forward is a pure JAX function, so it composes inside a larger model and runs under jit,
vmap, and grad. Useful gradients flow with respect to:
- the model parameters (
params), and - any continuous input substituted for the token lookup, for example a soft or one-hot embedding passed in place of integer ids.
The public interface takes integer tokens, which are discrete and do not themselves admit
gradients; to optimize a sequence through the encoder, feed a continuous representation rather than
token ids. In the seam folder, ablanx runs frozen as a fixed sequence prior.
What works today
- The Flax AbRep encoder,
ablang_jax.model.Ablanx. - The PyTorch-to-Flax weight key mapping,
ablang_jax.model.load_ablanx_params, which maps an AbLang2 AbRepstate_dict(as numpy arrays) into the Flax parameter tree. - A weight exporter,
export_weights.py, that writes the AbRep weight npz from the reference model. - A precompute script,
ablang_jax.precompute, that runs the reference PyTorch AbLang2 over a set of antibody records and stores per-residue embeddings.
Validation
The JAX forward reproduces reference PyTorch AbLang2 to float32 precision. Across a 30-Fv panel (25
paired VH+VL and 5 VH-only, drawn from public PDB structures), per-residue embeddings match the
reference with maximum absolute difference 3.9e-6 (median 2.4e-6 per Fv) and cosine above 0.999999,
using the same weights. The weights are byte-identical to the reference AbRep state_dict (207 tensors,
exact match). Reproduce with test_agreement.py.
Weights
The weights are the original AbLang2 AbRep weights, unmodified (207 tensors).
- Export from the reference model (works today, no release needed):
pip install ablang2 torch && python export_weights.pywritesablang2_weights.npz, verified byte-identical to the reference. - A torch-free
ablang2_weights.npzis also attached to the GitHub release once one is tagged.
Point ABLANG_WEIGHTS at the npz, or pass dict(np.load(...)) to load_ablanx_params.
Not included
- Only the AbRep encoder (embeddings and attention) is ported. The amino-acid likelihood head used for the pseudo-log-likelihood (sequence naturalness) is not part of this encoder port; use the reference AbLang2 for likelihoods.
Precompute
Precompute embeddings for a set of records with the reference PyTorch ablang2:
export ABLANG_JAX_DATA=/path/to/records
python -m ablang_jax.precompute --data $ABLANG_JAX_DATA
Input records are npz shards named {train,test}_*.npz; see ablang_jax/precompute.py for the
expected per-record fields. Outputs default to ./out/ when paths are not set.
Tests
python test_shapes.py # forward, weight-key mapping, masking
ABLANG_WEIGHTS=ablang2_weights.npz python test_agreement.py # agreement vs reference (needs weights)
test_shapes.py needs no weights. test_agreement.py loads the committed golden panel
(golden_ablang2_panel.npz, reference embeddings for 30 Fvs) and checks the JAX forward matches every
one; it skips under pytest if ABLANG_WEIGHTS is unset.
Attribution
- Original model, training, and weights: AbLang2, Oxford Protein Informatics Group. https://github.com/oxpig/AbLang2 (BSD-3-Clause, Copyright (c) 2021, Tobias Hegelund Olsen).
- Paper: Olsen, Moal, Deane, "Addressing the antibody germline bias and its effect on language models for improved antibody design", bioRxiv 2024, doi:10.1101/2024.02.02.578678.
- This port: Fabricagen.
ablanx is the language-model component of the seam bundle, a JAX antibody Fv structure predictor that couples jaxfvld with ablanx. For antibody developability screening and repair, see sift: https://sift.fabricagen.ai (coming soon, ca 08/26)
License
BSD-3-Clause. This port preserves the original AbLang2 copyright (Copyright (c) 2021, Tobias Hegelund
Olsen) and adds Copyright (c) 2026, Fabricagen for the port. The upstream AbLang2 license was
confirmed BSD-3-Clause. See ATTRIBUTION.md.
Metadata
Release files for ablanx 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ablanx-0.1.0.tar.gz | 9.1 kB | With provenance | Details for ablanx-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ablanx-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ablanx-0.1.0-py3-none-any.whl |
Total release size: 18.8 kB
Release files / ablanx-0.1.0.tar.gz
| Download URL | ablanx-0.1.0.tar.gz |
|---|---|
| Size | 9.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e96b5e62277dc4c1485c79f5973fc7ca50bbb63a545fa3b22c85c72d2726d8ec
|
|
BLAKE2b-256 checksum How to use checksums |
30cd10db8893f7659741a759889eba7ecc2c24399dc9e27a216ee9cf145b8668
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 21, 2026.
Transparency logRelease files / ablanx-0.1.0-py3-none-any.whl
| Download URL | ablanx-0.1.0-py3-none-any.whl |
|---|---|
| Size | 9.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a4c524edd6415b58a2d9e5acfba49cd635ff7fc6addc87a0566f0b9ce397ffee
|
|
BLAKE2b-256 checksum How to use checksums |
93748a9ecc36d94cffcbeb7bb67eb0df024f1f2383b50cb60581cb4b53943b87
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 21, 2026.
Transparency logSecurity for ablanx 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ablanx-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.