Improve model card and add metadata

README.md

@@ -1,12 +1,65 @@
 ---
-license: mit
-language:
-- en
 base_model:
 - meta-llama/Llama-3.1-8B-Instruct
+language:
+- en
+license: mit
+pipeline_tag: text-generation
+library_name: transformers
+tags:
+- hallucination-detection
+- faithfulness
 ---
 
+# FaithLens: Detecting and Explaining Faithfulness Hallucination
+
+FaithLens is a cost-efficient and effective model for **faithfulness hallucination detection** that jointly provides binary predictions and human-readable explanations. It helps in recognizing whether outputs from large language models (LLMs) contain faithfulness hallucination, which is crucial for applications like retrieval-augmented generation and summarization.
+
+The model is an 8B-parameter model, initialized with `meta-llama/Llama-3.1-8B-Instruct`, and optimized through a two-stage process involving cold-start supervised fine-tuning (SFT) and rule-based reinforcement learning (RL). It has been shown to outperform advanced models such as GPT-4.1 and o3 across 12 diverse tasks.
+
+- **Paper:** [FaithLens: Detecting and Explaining Faithfulness Hallucination](https://huggingface.co/papers/2512.20182)
+- **Repository:** [https://github.com/S1s-Z/FaithLens](https://github.com/S1s-Z/FaithLens)
+
+## Usage
+
+You can use FaithLens by installing its dedicated package and running the provided inference script.
+
+First, install the package:
+```sh
+pip install "faithlens @ git+https://github.com/S1s-Z/FaithLens.git@master"
+```
+
+Then, you can use the following Python code for inference:
+
+```python
+from faithlens.inference import FaithLensInfer
+import json
+
+# Predicted Label:
+# 0 indicates the claim is hallucinated (the claim is not supported by the document)
+# 1 indicates the claim is faithful (supported by the document)
+
+detection_model = FaithLensInfer(model_name="ssz1111/FaithLens", device="cuda:0")
+single_result = detection_model.infer(
+    docs=["Relegation-threatened Romanian club Ceahlaul Piatra Neamt have sacked Brazilian coach Ze Maria for the second time in a week. Former Brazil defender Ze Maria was fired on Wednesday after a poor run, only to be reinstated the next day after flamboyant owner Angelo Massone decided to 'give the coaching staff another chance.' But the 41-year-old former Inter Milan and Parma right back, capped 25 times by Brazil, angered Massone again after Ceahlaul were beaten 2-0 by mid-table FC Botosani on Saturday. Ze Maria represented Brazil on 25 occasions during an international career spanning five years . The result left Ceahlaul 16th in the standings, six points adrift of safety. Ze Maria replaced Florin Marin in January to become Ceahlaul's third coach this season. He will be replaced by Serbian Vanya Radinovic."],
+    claims=["Former brazil defender ze maria was fired on wednesday after a poor run. The 41-year-old was reinstated the next day after flamboyant owner angelo massone decided to'give the coaching staff another chance' but the 41-year-old angered massone again after ceahlaul were beaten 2-0 by mid-table fc botosani on saturday."],
+)
+print("Single Result:")
+print(json.dumps(single_result, ensure_ascii=False, indent=2))
+```
+
+## Citation
 
-# FaithLens
+If you use FaithLens in your research, please cite the following paper:
 
-A simple demo for the deployment of the model can be found in https://github.com/S1s-Z/FaithLens.
+```bibtex
+@misc{si2025faithlensdetectingexplainingfaithfulness,
+      title={FaithLens: Detecting and Explaining Faithfulness Hallucination}, 
+      author={Shuzheng Si and Qingyi Wang and Haozhe Zhao and Yuzhuo Bai and Guanqiao Chen and Kangyang Luo and Gang Chen and Fanchao Qi and Minjia Zhang and Baobao Chang and Maosong Sun},
+      year={2025},
+      eprint={2512.20182},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL},
+      url={https://arxiv.org/abs/2512.20182}, 
+}
+```