Improve model card: add library name, update license, link paper, and enhance content

README.md

@@ -1,29 +1,35 @@
 ---
-license: apache-2.0
-language:
-- en
 base_model:
 - state-spaces/mamba2-130m
+language:
+- en
+license: mit
 pipeline_tag: question-answering
+library_name: transformers
 ---
 
-# Single-Pass Scanner
+# Single-Pass Document Scanning for Question Answering
+
+This repository contains the model checkpoint for **Single-Pass Scanner**, a method introduced in the paper [Single-Pass Document Scanning for Question Answering](https://huggingface.co/papers/2504.03101).
 
-This repository contains model checkpoint for [Single-Pass Scanner](https://github.com/MambaRetriever/MambaRetriever)
+The model architecture is built upon [mamba](https://github.com/state-spaces/mamba), and is trained from [mamba2-130m](https://huggingface.co/state-spaces/mamba2-130m).
 
-The model architecture is built upon [mamba](https://github.com/state-spaces/mamba), and is trained from [mamba2-130m](https://huggingface.co/state-spaces/mamba2-130m)
+## Abstract
+Handling extremely large documents for question answering is challenging: chunk-based embedding methods often lose track of important global context, while full-context transformers can be prohibitively expensive for hundreds of thousands of tokens. We propose a single-pass document scanning approach that processes the entire text in linear time, preserving global coherence while deciding which sentences are most relevant to the query. On 41 QA benchmarks, our single-pass scanner consistently outperforms chunk-based embedding methods and competes with large language models at a fraction of the computational cost. By conditioning on the entire preceding context without chunk breaks, the method preserves global coherence, which is especially important for long documents. Overall, single-pass document scanning offers a simple solution for question answering over massive text.
 
+## Code and Project Page
+The official GitHub repository for the project, containing all code, datasets, and additional details, is available at: [https://github.com/MambaRetriever/MambaRetriever](https://github.com/MambaRetriever/MambaRetriever).
 
-# Usage
+## Installation
 
 We highly recommend creating a new conda environment first:
-```
+```bash
 conda create -n mamba_retriever python=3.10.14
 conda activate mamba_retriever
 ```
 
-Then, run the following in your terminal:
-```
+Then, run the following in your terminal to install necessary packages and the `mamba` library:
+```bash
 git clone https://github.com/state-spaces/mamba.git
 conda install cudatoolkit==11.8 -c nvidia
 pip install -r requirements.txt
@@ -33,18 +39,54 @@ cd mamba
 pip install .
 ```
 
-Next, download and install the following two files from https://github.com/state-spaces/mamba/releases and https://github.com/Dao-AILab/causal-conv1d/releases:
-```
-mamba_ssm-2.2.2+cu118torch2.1cxx11abiFALSE-cp310-cp310-linux_x86_64.whl
-causal_conv1d-1.4.0+cu118torch2.1cxx11abiFALSE-cp310-cp310-linux_x86_64.whl
-```
+Next, download and install the following two `.whl` files for Mamba dependencies from their respective releases pages:
+- `mamba_ssm-2.2.2+cu118torch2.1cxx11abiFALSE-cp310-cp310-linux_x86_64.whl` from [https://github.com/state-spaces/mamba/releases](https://github.com/state-spaces/mamba/releases)
+- `causal_conv1d-1.4.0+cu118torch2.1cxx11abiFALSE-cp310-cp310-linux_x86_64.whl` from [https://github.com/Dao-AILab/causal-conv1d/releases](https://github.com/Dao-AILab/causal-conv1d/releases)
 
-You can install them using
-```
+You can install them using `pip`:
+```bash
 pip install mamba_ssm-2.2.2+cu118torch2.1cxx11abiFALSE-cp310-cp310-linux_x86_64.whl
 pip install causal_conv1d-1.4.0+cu118torch2.1cxx11abiFALSE-cp310-cp310-linux_x86_64.whl
 ```
 
-## Evaluation
+## Usage
+
+Our model checkpoints are available at [Hugging Face](https://huggingface.co/MambaRetriever). You can load the model using the `transformers` library with `trust_remote_code=True`.
+
+```python
+from transformers import AutoModelForSequenceClassification, AutoTokenizer
+import torch
+
+# Load the model and tokenizer
+model_name = "MambaRetriever/SPScanner-130m"
+tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
+model = AutoModelForSequenceClassification.from_pretrained(model_name, trust_remote_code=True)
+
+# Move model to GPU if available
+if torch.cuda.is_available():
+    model = model.cuda()
+
+# Example usage (simplified for demonstration, refer to GitHub for full pipeline)
+question = "What is the capital of France?"
+context = "Paris is the capital and most populous city of France."
+
+# Tokenize input (example, actual tokenization depends on dataset format and model's specific use case)
+# This model is for document scanning/retrieval; actual usage involves processing long documents.
+# The following is a conceptual example for basic model loading and forward pass.
+inputs = tokenizer(question, context, return_tensors="pt", truncation=True, max_length=512)
+
+# Move inputs to GPU if model is on GPU
+if torch.cuda.is_available():
+    inputs = {k: v.cuda() for k, v in inputs.items()}
+
+# Get model outputs (e.g., relevance scores for sentences/chunks)
+with torch.no_grad():
+    outputs = model(**inputs)
+
+# Further processing to extract answer would follow, as per the official repository's pipeline.
+print("Model output logits (example for a classification task):", outputs.logits)
+```
+
+## Evaluation and Training
 
-All evaluation code and details are available at [Single-Pass Scanner Github](https://github.com/MambaRetriever/MambaRetriever)
+All detailed evaluation code and scripts, as well as training instructions and synthetic data generation steps, are available in the [Single-Pass Scanner GitHub repository](https://github.com/MambaRetriever/MambaRetriever). Please refer to the `run_evaluation.sh` and `run_training.sh` scripts, along with the `Synthetic Data Generation` section in the GitHub README, for comprehensive guidance.