Add TCR-BERT predictor / TCR embedder wrapper

[iskandr]

Wrap TCR-BERT as an mhctools predictor / TCR embedder.

Upstream: https://github.com/wukevin/tcr-bert — a BERT model pretrained on TCR sequences, with a fixed-label antigen-specificity classifier head.

Pretrained weights: on HuggingFace — wukevin/tcr-bert (~219 MB) and wukevin/tcr-bert-mlm-only. Auto-downloaded via the standard transformers API; no manual step.

Framework / deps: PyTorch + transformers (upstream used 4.4.2, but it's a standard BERT and should load on modern transformers).

License: Apache-2.0 — the cleanest license of the benchmark set; weights are freely redistributable.

Inputs / output: CDR3 sequence (no MHC). Two use modes: (1) sequence embeddings, and (2) a classifier over a fixed antigen label set — so it predicts specificity against known epitopes rather than scoring an arbitrary (peptide, TCR) pair. Worth capturing this limitation in the wrapper's docs.

Ease: Easy. from transformers import ..., auto-download, standard forward pass.

Suggested wrapping approach: in-process via transformers as an optional extra (mhctools doesn't depend on transformers today). Expose embeddings + the fixed-label classifier; be explicit that it isn't an arbitrary-epitope binding scorer.

---

Surfaced from a survey of TCREpitopeBenchmark for methods with public pretrained weights that run easily for inference.

https://claude.ai/code/session_01LZahFhBSCiehXTESCYQ7wG

[iskandr]

⚠️ Read before investing effort: the generalization ceiling

Every TCR–epitope binding predictor in this backlog — this one included — shares a well-documented limitation: they do only modestly on epitopes seen in training and drop to near-random on unseen/novel epitopes. Independent benchmarks find that no current method reliably generalizes; the "best" scores on unseen data sit around the random floor (e.g. mean AUPRC ~0.52–0.53). A tool can look decent on a test set dominated by common epitopes (GILGFVFTL, NLVPMVATV, …) purely because those TCRs saturate the public databases, then fail on anything new.

References

• Moris et al. 2021, Briefings in Bioinformatics — Current challenges for unseen-epitope TCR interaction prediction (foundational: the unseen-epitope challenge, negative-data bias, imbalanced-epitope distribution)
• Meysman et al. 2023, ImmunoInformatics — Benchmarking solutions to the TCR epitope prediction problem: IMMREP22 workshop report (first public benchmark, 23 models) and the IMMREP23 follow-up
• Nature Methods 2025 — Assessment of computational methods in predicting TCR–epitope binding recognition

Implication for this wrapper: worthwhile for reproducibility, cross-method benchmarking, and the well-characterized "seen-epitope" regime — not as a trustworthy predictor for novel epitopes / neoantigens. When we build it, the wrapper's docstring should state this ceiling so users don't over-trust the output.