Improve model card: Add pipeline tag, library name, code/project links, and sample usage

This PR enhances the model card for Klear-Reasoner-8B by:

* Adding `pipeline_tag: text-generation` to accurately reflect the model's capabilities in long-form reasoning and code generation. This will also improve discoverability on the Hugging Face Hub (e.g., at https://huggingface.co/models?pipeline_tag=text-generation).
* Including `library_name: transformers` metadata, as the model is compatible with the 🤗 Transformers library, enabling the "how to use" widget and further improving discoverability.
* Adding a direct link to the main GitHub repository (`https://github.com/suu990901/Klear_Reasoner`) and the project page (`https://suu990901.github.io/KlearReasoner/`) in the resource table for easier access to related resources.
* Integrating a clear Python code snippet for sample usage, making it easier for users to get started with inference.
* Adding a detailed section on GPPO (Gradient-Preserving Clipping Policy Optimization) for a deeper understanding of the model's core innovation.

These updates improve the completeness and usability of the model card.

README.md

@@ -1,17 +1,18 @@
 ---
-license: apache-2.0
-language:
-- en
 base_model:
 - Qwen/Qwen3-8B-Base
 datasets:
 - Suu/KlearReasoner-MathSub-30K
 - Suu/KlearReasoner-CodeSub-15K
+language:
+- en
+license: apache-2.0
 metrics:
 - accuracy
+pipeline_tag: text-generation
+library_name: transformers
 ---
 
-
 # ✨ Klear-Reasoner-8B
 We present Klear-Reasoner, a model with long reasoning capabilities that demonstrates careful deliberation during problem solving, achieving outstanding performance across multiple benchmarks. We investigate two key issues with current clipping mechanisms in RL: Clipping suppresses critical exploration signals and ignores suboptimal trajectories. To address these challenges, we propose **G**radient-**P**reserving clipping **P**olicy **O**ptimization (**GPPO**) that gently backpropagates gradients from clipped tokens.  
 
@@ -19,10 +20,12 @@ We present Klear-Reasoner, a model with long reasoning capabilities that demonst
 |---|---|
 | 📝 Preprints | [Paper](https://arxiv.org/pdf/2508.07629) |
 | 🤗 Daily Paper | [Paper](https://huggingface.co/papers/2508.07629) |
+| 🌐 Project Page | [Klear-Reasoner Website](https://suu990901.github.io/KlearReasoner/) |
+| 💻 Code Repo | [Klear-Reasoner GitHub](https://github.com/suu990901/Klear_Reasoner) |
 | 🤗 Model Hub | [Klear-Reasoner-8B](https://huggingface.co/Suu/Klear-Reasoner-8B) |
 | 🤗 Dataset Hub | [Math RL](https://huggingface.co/datasets/Suu/KlearReasoner-MathSub-30K) |
 | 🤗 Dataset Hub | [Code RL](https://huggingface.co/datasets/Suu/KlearReasoner-CodeSub-15K) |
-| 🐛 Issues & Discussions | [GitHub Issues](https://github.com/suu990901/KlearReasoner/issues) |
+| 🐛 Issues & Discussions | [GitHub Issues](https://github.com/suu990901/Klear_Reasoner/issues) |
 | 📧 Contact | [email protected] |
 
 ## 📌 Overview
@@ -45,6 +48,69 @@ The model combines:
 
 ---
 
+## 📐 GPPO (Gradient-Preserving Clipping Policy Optimization)
+
+GPPO is a **plug-and-play** replacement for PPO/GRPO that keeps the clipped tokens **in the computational graph** and lets their gradients flow in a **bounded, controlled** way.
+
+
+### Problem with Vanilla Clipping  
+Classic importance-ratio clipping (PPO/GRPO) drops all tokens whose ratio  
+$r_t^{(j)}=\pi_\theta/\pi_{\text{old}}$ falls outside $[1-\varepsilon_l,\ 1+\varepsilon_h]$.  
+Two side-effects appear:
+
+- **High-entropy exploratory tokens** (large $r$, positive advantage) are killed → less exploration.  
+- **Negative trajectories** (small $r$, negative advantage) are ignored → slower correction.
+
+
+### GPPO Surrogate Loss (Token-Level GRPO)  
+
+Let  
+- $\delta = r_t^{(j)}(\theta)=\pi_\theta/\pi_{\text{old}}$ (importance ratio)  
+- $\tilde A^{(j)}$ = group-relative advantage  
+- $\text{sg}(\cdot)$ = stop-gradient (detach from back-prop)
+
+The **GPPO objective** is  
+
+
+![GPPO Loss](CodeCogsEqn.svg)
+
+
+- **Forward**: behaves exactly like Clip-Higher.  
+- **Backward**: the fraction $\frac{1\pm\varepsilon}{\text{sg}(\delta)}$ keeps the clipped magnitude **but still propagates** a mild gradient.
+
+
+### Gradient Expression  
+
+Let $\phi_\theta(a_{j,t},s_{j,t})$ be the policy-gradient vector.  
+The **per-token gradient** is  
+
+![gard](CodeCogsEqn_1.svg)
+
+
+where  
+
+![condtion](CodeCogsEqn_2.svg)
+
+- **Never zero** → every token contributes to learning.
+
+
+### General Form with Tunable Scaling ($\beta_1$, $\beta_2$)  
+
+For finer-grained control:  
+
+![general_loss](CodeCogsEqn_3.svg)
+
+Empirically we set $\beta_1 = \beta_2 = 1$.
+
+### Experiment
+<div align="center">
+<img src="GPPO.png" width="100%"/>
+
+<sub>Comparison of GPPO, GRPO w/ Clip Higher, and CISPO in mathematical RL training. Both methods are trained from an earlier long-CoT SFT checkpoint with a sequence length of 32K tokens. For GRPO, we use the Clip-Higher strategy from DAPO with the recommended $$\epsilon_h = 0.28$$.</sub>
+</div>
+
+---
+
 ### Evaluation
 When we expand the inference budget to 64K and adopt the YaRN method with a scaling factor of 2.5. **Evaluation is coming soon, stay tuned.**  
 
@@ -66,6 +132,36 @@ When we expand the inference budget to 64K and adopt the YaRN method with a scal
 
 > We report the average `pass@1` results (avg@_n_), with all other evaluation metrics following the DeepSeek-R1 assessment framework (temperature=0.6, top_p=0.95).  
 
+---
+
+## Usage
+You can load the model and perform inference using the Hugging Face `transformers` library:
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+import torch
+
+model_name = "Suu/Klear-Reasoner-8B" # or "Suu/Klear-Reasoner-8B-SFT"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    torch_dtype=torch.bfloat16,
+    device_map="auto"
+)
+
+prompt = "Prove that for all positive integers n, n^3 + 2n is divisible by 3."
+messages = [{"role": "user", "content": prompt}]
+inputs = tokenizer.apply_chat_template(messages, return_tensors="pt").to(model.device)
+
+outputs = model.generate(
+    inputs,
+    max_new_tokens=8192,
+    temperature=0.6,
+    top_p=0.95,
+    do_sample=True
+)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
 
 ---
 
@@ -78,6 +174,33 @@ pip install -r requirements.txt
 ```
 For the code, we use [Firejail](https://github.com/netblue30/firejail) for the **sandbox** environment. Additionally, we implemented multi-process control based on [Pebble](https://github.com/noxdafox/pebble), enabling automatic resource reclamation upon task timeout. For mathematics, we use [math_verify](https://github.com/huggingface/Math-Verify) for judging.
 
+### Training Data Format
+Please refer to the format of the two provided datasets, [Math RL](https://huggingface.co/datasets/Suu/KlearReasoner-MathSub-30K) and [Code RL](https://huggingface.co/datasets/Suu/KlearReasoner-CodeSub-15K), for the training data. The format for a single math entry is as follows:  
+```json
+{"data_source": "math_longcot_math_verify", "prompt": [{"content": "Let $n=9867$. If you calculated $n^{3}-n^{2}$, what would be the unit digit found?\
+(a) 0\
+(b) 2\
+(c) 4\
+(d) 6\
+(e) 8", "role": "user"}], "ability": "math", "reward_model": {"ground_truth": "4", "style": "rule"}, "__index_level_0__": "29999"}  
+```
+  
+Here, the data_source field is set to "math_longcot_math_verify".  
+
+The format for a single code entry is as follows:  
+```json
+{"hash": "47c43857280be8a7557cc36b998b3012", "ability": "code", "data_source": "coder1_longcot", "prompt": [{"content": "You are an expert Python programmer. You will be given a question (problem specification) and will generate a correct Python program that matches the specification and passes all tests.\
+\
+Takahashi is planning to eat N dishes.\
+The i-th dish he plans to eat is sweet if S_i = sweet, and salty if S_i = salty.\
+If he eats two sweet dishes consecutively, he will feel sick and be unable to eat any more dishes.\
+Determine whether he can eat all the dishes...", "role": "user"}], "reward_model": {"ground_truth": "...", "style": "rule"}}  
+```
+
+Here, the data_source field is set to "coder1_longcot".
+
+**The data_source field affects the choice of verifier.**
+
 ### Using Ray for Multi-Node Training
 For multi-node training​​, ensure ​​all nodes are started and connected via Ray​​ before executing the training script. Below is a brief setup guide for Ray across multiple machines:
 #### Step 1: Start Ray on the Head Node (node0)
@@ -116,6 +239,7 @@ YOUR_TRAIN_FILE="<train_data_path>"
 YOUR_TEST_FILE="<test_data_path>"
 ```
 
+---
 ## 🤝 Citation
 If you find this work helpful, please cite our paper:
 ```bibtex