Update README.md

README.md

@@ -18,32 +18,52 @@ inference: true
 
 # Mizan-Rerank-v2
 
-A high-performance open-source cross-encoder model for reranking Arabic long texts, fine-tuned from Alibaba-NLP/gte-multilingual-reranker-base with state-of-the-art results on Arabic reranking benchmarks.
+A cross-encoder model for reranking Arabic long texts, fine-tuned from Alibaba-NLP/gte-multilingual-reranker-base.
 
 ![Hugging Face](https://img.shields.io/badge/Hugging%20Face-Mizan--Rerank--v2-blue)
 ![Model Size](https://img.shields.io/badge/Parameters-305M-green)
 ![License](https://img.shields.io/badge/License-Apache%202.0-brightgreen)
-[![Demo](https://img.shields.io/badge/🤗%20Demo-Mizan--Rerank--V2-yellow)](https://huggingface.co/spaces/ALJIACHI/Mizan-Rerank-V2-Demo)
+![Deprecated](https://img.shields.io/badge/Status-Deprecated-red)
+[![Replacement](https://img.shields.io/badge/Replacement-Mizan--Rerank--v3-orange)](https://huggingface.co/ALJIACHI/Mizan-Rerank-v3/)
 
-## Try It Out
+---
+
+## Deprecated: use Mizan-Rerank-v3
+
+> **This model is deprecated and no longer maintained. Use [Mizan-Rerank-v3](https://huggingface.co/ALJIACHI/Mizan-Rerank-v3/) instead.**
+>
+> v3 is a 306M-parameter cross-encoder, fine-tuned from the same [Alibaba-NLP/gte-multilingual-reranker-base](https://huggingface.co/Alibaba-NLP/gte-multilingual-reranker-base) base as v2 but on 71k Arabic listwise groups whose hard negatives are adversarial traps: negated rulings, swapped entities, shifted numbers and dates, exceptions applied to the wrong case. It scores higher than v2 on every held-out benchmark we measure, and it runs about twice as fast as bge-reranker-v2-m3.
+>
+> v3 is trained from the base model rather than from v2, so it is a replacement rather than a continuation. v3 covers the use cases v2 was built for, so there is no reason to start a new project on v2. This card is kept online for reproducibility of existing work.
+
+### v2 vs. v3 at a glance
 
-<iframe
-  src="https://ALJIACHI-Mizan-Rerank-V2-Demo.hf.space"
-  frameborder="0"
-  width="100%"
-  height="600"
-></iframe>
+| | Mizan-Rerank-v2 | Mizan-Rerank-v3 |
+|---|---|---|
+| Status | **deprecated** | **recommended** |
+| Parameters | 305M | 306M |
+| Base model | Alibaba-NLP/gte-multilingual-reranker-base | Alibaba-NLP/gte-multilingual-reranker-base |
+| Trained from | the gte base | the gte base (not from v2) |
+| Training data | 1,199,634 Arabic query–document pairs | 71,044 Arabic listwise groups with adversarial hard negatives |
+| Held-out Arabic benchmarks | baseline | **higher on every set** |
+| Best for | — | RAG, long-document retrieval, domain-specific Arabic search |
 
-> **[Open full demo →](https://huggingface.co/spaces/ALJIACHI/Mizan-Rerank-V2-Demo)**
+Migrating is a one-line change — see [Migrating to v3](#migrating-to-v3) below.
+
+---
 
 ## Overview
 
-Mizan-Rerank-v2 is a cross-encoder reranking model based on [Alibaba-NLP/gte-multilingual-reranker-base](https://huggingface.co/Alibaba-NLP/gte-multilingual-reranker-base), specifically fine-tuned for Arabic text reranking. It excels at reranking long documents (up to 8192 tokens) and outperforms both its base model and larger competitors on Arabic reranking benchmarks.
+Mizan-Rerank-v2 is a cross-encoder reranking model based on [Alibaba-NLP/gte-multilingual-reranker-base](https://huggingface.co/Alibaba-NLP/gte-multilingual-reranker-base), fine-tuned for Arabic text reranking. It handles long documents (up to 8192 tokens) and was the state of the art in the Mizan family when it was released. It is now superseded by v3.
+
+### Legacy demo
+
+The v2 demo space is still online at [ALJIACHI/Mizan-Rerank-V2-Demo](https://huggingface.co/spaces/ALJIACHI/Mizan-Rerank-V2-Demo). It serves v2; use v3 for new work.
 
 ## Key Features
 
 - **Long Document Support**: Handles up to 8192 tokens using RoPE position embeddings with NTK scaling
-- **Superior Arabic Performance**: Outperforms BAAI/bge-reranker-v2-m3 (568M) despite being nearly half the size
+- **Compact for its quality**: 305M parameters, roughly half the size of BAAI/bge-reranker-v2-m3 (568M)
 - **Arabic Language Optimization**: Fine-tuned on 1.2M+ Arabic query-document pairs from diverse sources
 
 ## Performance Benchmarks
@@ -52,6 +72,8 @@ Mizan-Rerank-v2 is a cross-encoder reranking model based on [Alibaba-NLP/gte-mul
 
 ### Reranking Evaluation (ndcg@10)
 
+The table below comes from the evaluation run used for the v2 release, so all models are measured under identical conditions and the numbers are directly comparable. It predates v3.
+
 | Model | Parameters | Reranking | Triplet | MIRACL (Long Docs) | WikiQA | MedQA |
 |-------|-----------|-----------|---------|---------------------|--------|-------|
 | **Mizan-Rerank-v2** | **305M** | **1.0000** | 0.9993 | **0.8091** | 0.8258 | **0.6775** |
@@ -89,6 +111,8 @@ Mizan-Rerank-v2 is a cross-encoder reranking model based on [Alibaba-NLP/gte-mul
 - **Number of Output Labels:** 1
 - **Language:** Arabic (ar), English (en)
 - **License:** Apache 2.0
+- **Status:** deprecated
+- **Replacement:** [ALJIACHI/Mizan-Rerank-v3](https://huggingface.co/ALJIACHI/Mizan-Rerank-v3/)
 
 ## Usage
 
@@ -164,6 +188,22 @@ for passage, score in reranked:
     print(f"Score: {score:.4f} | {passage[:80]}...")
 ```
 
+## Migrating to v3
+
+The interface is identical; only the model ID changes. Both models need `trust_remote_code=True`:
+
+```python
+from sentence_transformers import CrossEncoder
+
+# Before
+model = CrossEncoder("ALJIACHI/Mizan-Rerank-v2", max_length=8192, trust_remote_code=True)
+
+# After
+model = CrossEncoder("ALJIACHI/Mizan-Rerank-v3", max_length=3072, trust_remote_code=True)
+```
+
+Scores are not calibrated across versions, so if your pipeline uses an absolute score threshold to filter candidates, re-tune that threshold after switching. Full details, benchmarks and a usage guide are on the [v3 model card](https://huggingface.co/ALJIACHI/Mizan-Rerank-v3/).
+
 ## Training Details
 
 ### Training Data
@@ -196,6 +236,8 @@ Trained on **1,199,634 query-document pairs** from diverse Arabic sources
 - Long-document Arabic content analysis
 - E-learning platforms with Arabic content
 
+For all of the above, use v3. This model is deprecated and is documented here only for reproducibility of existing work.
+
 ### Framework Versions
 
 - Python: 3.10.14
@@ -218,6 +260,18 @@ Trained on **1,199,634 query-document pairs** from diverse Arabic sources
 }
 ```
 
+For the recommended model:
+
+```bibtex
+@software{Mizan_Rerank_v3_2026,
+  author = {Ali Aljiachi},
+  title = {Mizan-Rerank-v3: Adversarially Trained Arabic Long-Context Reranker},
+  year = {2026},
+  publisher = {Hugging Face},
+  url = {https://huggingface.co/ALJIACHI/Mizan-Rerank-v3}
+}
+```
+
 ```bibtex
 @inproceedings{reimers-2019-sentence-bert,
     title = "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks",