Update README.md

README.md

@@ -1,38 +1,129 @@
 ---
-library_name: sentence-transformers
 license: apache-2.0
+language:
+- en
 base_model:
 - Qwen/Qwen3-VL-Reranker-2B
 pipeline_tag: text-ranking
+library_name: sentence-transformers
 tags:
-- supertron2
-- reranker
-- qwen3-vl
-- text-ranking
+- reranking
+- retrieval
+- rag
 - cross-encoder
-language:
-- en
+- qwen3-vl
+- pytorch
+---
+
+# **Supertron2-Reranker-2B: A Compact Cross-Encoder Reranking Model**
+
+## **Model Description**
+
+**Supertron2-Reranker-2B** is a reranking model built on top of [Qwen/Qwen3-VL-Reranker-2B](https://huggingface.co/Qwen/Qwen3-VL-Reranker-2B). It is designed to score query-document pairs for retrieval pipelines, search systems, and RAG applications where a stronger second-stage ranker is useful.
+
+* **Developed by:** Surpem
+* **Model type:** Cross-Encoder Reranker
+* **Architecture:** Qwen3-VL reranker, 2B parameters
+* **License:** Apache 2.0
+
 ---
 
-# Supertron2-Reranker-2B
+## **Capabilities**
+
+### **Search Reranking**
+
+Supertron2-Reranker-2B can compare a user query against candidate passages and assign relevance scores. It is intended as a second-stage reranker after a faster retriever has already selected candidate documents.
+
+### **RAG Pipelines**
+
+The model can help improve retrieval-augmented generation by pushing more relevant documents toward the top of the context window before answer generation.
 
-Supertron2-Reranker-2B is a short fine-tune of `Qwen/Qwen3-VL-Reranker-2B` for text reranking.
+### **Question-Document Matching**
 
-It is trained on real reranking pairs, primarily MS MARCO, for search and RAG reranking.
+Supertron2-Reranker-2B is useful for matching questions to passages, snippets, help-center articles, documentation chunks, and other text candidates.
 
-## Usage
+### **Instruction-Aware Retrieval**
+
+The model is prompted for relevance scoring, making it suitable for natural language search tasks where query intent matters.
+
+---
+
+## **Get Started**
 
 ```python
 from sentence_transformers import CrossEncoder
 
-model = CrossEncoder("Surpem/Supertron2-Reranker-2B")
-scores = model.predict([
-    ("What is the capital of France?", "Paris is the capital of France."),
-    ("What is the capital of France?", "Mars is the red planet."),
-])
+model_id = "Surpem/Supertron2-Reranker-2B"
+
+model = CrossEncoder(model_id)
+
+pairs = [
+    ("What is the capital of France?", "Paris is the capital and largest city of France."),
+    ("What is the capital of France?", "Mars is often called the red planet."),
+]
+
+scores = model.predict(pairs)
 print(scores)
 ```
 
-## Limitations
+Example reranking:
+
+```python
+query = "How do I reset my password?"
+documents = [
+    "Use the account recovery page to reset your password.",
+    "Our refund policy allows returns within 30 days.",
+    "Two-factor authentication adds extra login security.",
+]
+
+results = model.rank(query, documents)
+print(results)
+```
+
+---
+
+## **Hardware Requirements**
+
+| Precision | Min VRAM | Recommended |
+|---|---|---|
+| bfloat16 | 6 GB | 10 GB+ |
+| 4-bit quantized | 3 GB | 6 GB+ |
+
+For larger batches or long documents, use more VRAM or reduce the batch size/max sequence length.
+
+---
+
+## **Intended Use**
+
+Supertron2-Reranker-2B is intended for:
+
+* Search reranking
+* RAG document reranking
+* Query-passage relevance scoring
+* Documentation and knowledge-base retrieval
+* Evaluation of candidate retrieval results
+
+It is not intended to be used as a standalone chat model.
+
+---
+
+## **Limitations**
+
+* The model scores relevance; it does not generate answers.
+* It should be evaluated on your own retrieval domain before production use.
+* Long documents may need chunking before reranking.
+* Relevance scores are relative and may not be calibrated across unrelated queries.
+* The model may still rank incorrect, outdated, or unsafe content highly if it appears textually relevant.
+
+---
+
+## **Citation**
 
-This is a short 30-minute H100 fine-tune. It should be evaluated on your retrieval domain before production use.
+```bibtex
+@misc{surpem2026supertron2-reranker-2b,
+      title={Supertron2-Reranker-2B -- Compact Cross-Encoder Reranking Model},
+      author={Surpem},
+      year={2026},
+      url={https://huggingface.co/Surpem/Supertron2-Reranker-2B},
+}
+```