ViTax-RAG: a retrieval-augmented language modeling tool for viral contig taxonomic classification

Taxonomic classification of viral metagenomic contigs remains difficult for short or divergent sequences. Reference-based methods are precise when close homologs exist, whereas representation-based models can generalize beyond direct matches but lack explicit biological evidence.

Here, we present ViTax-RAG, a retrieval-augmented framework that integrates alignment-derived evidence with learned sequence representations for robust viral classification. ViTax-RAG reformulates BLAST as a domain-specific retrieval module and integrates retrieved homology information into a sequence modeling framework, thereby enabling the complementary use of alignment-based and representation-based signals. We evaluated ViTax-RAG on in-distribution (ID) and within-genus out-of-distribution (OOD) datasets, where it consistently outperformed current viral taxonomy methods at comparable taxonomic endpoints and supported fragment lengths. The pipeline processed all 195 728 GOV 2.0 contigs; 87.2% of predictions terminated at class, demonstrating hierarchical backoff rather than fine-rank accuracy on data without ground truth.

ViTax-RAG is implemented in Python and is freely available at GitHub (https://github.com/Ying-Lab/ViTax-Rag) under an open-source license. Documentation and example workflows are provided to facilitate integration into metagenomic analysis pipelines.