Update TrustSQL-8B model card

README.md

@@ -1,17 +1,18 @@
 ---
-library_name: transformers
 license: apache-2.0
+library_name: transformers
 pipeline_tag: text-generation
-base_model:
-- Qwen/Qwen3-8B
 tags:
-- text2sql
-- sql
-- trustworthy
-- qwen3
+  - text-to-sql
+  - sql
+  - unknown-schema
+  - tool-use
+  - reinforcement-learning
+  - qwen3
+base_model: Qwen/Qwen3-8B
 ---
 
-# TrustSQL-8B
+# TRUST-SQL-8B
 
 [![arXiv](https://img.shields.io/badge/arXiv-2603.16448-b31b1b.svg)](https://arxiv.org/abs/2603.16448)
 [![GitHub](https://img.shields.io/badge/GitHub-TrustSQL-black?logo=github)](https://github.com/JaneEyre0530/TrustSQL)
@@ -19,85 +20,88 @@ tags:
 
 ## Overview
 
-**TrustSQL-8B** is a fine-tuned Text-to-SQL model based on [Qwen3-8B](https://huggingface.co/Qwen/Qwen3-8B), introduced in the paper [TRUST-SQL: Tool-Integrated Multi-Turn Reinforcement Learning for Text-to-SQL over Unknown Schemas](https://arxiv.org/abs/2603.16448). The model is trained via multi-turn reinforcement learning with tool integration, enabling accurate SQL generation over unknown database schemas.
+**TrustSQL-8B** is a fine-tuned Text-to-SQL model based on [Qwen3-8B](https://huggingface.co/Qwen/Qwen3-8B), introduced in [TRUST-SQL: Tool-Integrated Multi-Turn Reinforcement Learning for Text-to-SQL over Unknown Schemas](https://arxiv.org/abs/2603.16448). The model is trained with multi-turn reinforcement learning and tool integration for Text-to-SQL over unknown database schemas.
 
-This model is part of the **TRUST-SQL** series, which focuses on building trustworthy Text-to-SQL systems capable of handling real-world scenarios where the database schema is not fully known in advance.
+## Model details
 
-## Model Details
-
-| Attribute | Value |
-|-----------|-------|
-| Base Model | Qwen/Qwen3-8B |
-| Architecture | Qwen3ForCausalLM |
-| Parameters | 8.2B |
-| Hidden Size | 4096 |
-| Layers | 36 |
-| Attention Heads | 32 (Q) / 8 (KV, GQA) |
-| Context Length | 40,960 tokens |
-| Precision | bfloat16 |
+- Base model: `Qwen/Qwen3-8B`
+- Architecture: `Qwen3ForCausalLM`
+- Parameters: 8.2B
+- Hidden size: 4096
+- Layers: 36
+- Attention heads: 32 Q heads / 8 KV heads
+- Context length: 40,960 tokens
+- Precision: bfloat16
 
 ## Models
 
 | Model | Base | Link |
-|-------|------|------|
+|---|---|---|
 | TrustSQL-4B | Qwen3-4B | [AIJian/TrustSQL-4B](https://huggingface.co/AIJian/TrustSQL-4B) |
 | TrustSQL-8B | Qwen3-8B | [AIJian/TrustSQL-8B](https://huggingface.co/AIJian/TrustSQL-8B) |
 
-## Usage
+## Training
+
+TrustSQL follows a two-stage training pipeline: SFT warm-up followed by Phase-Aware GRPO optimization. The interaction protocol is `Explore → Propose → Generate → Confirm`.
+
+## Reported results
+
+All results are reported under the Unknown Schema setting.
+
+| Benchmark | Greedy | Majority voting |
+|---|---:|---:|
+| BIRD-Dev | 65.8 | 67.7 |
+| Spider-Test | 83.9 | 86.5 |
+| Spider-DK | 72.1 | 75.7 |
+| Spider-Syn | 75.4 | 77.4 |
+| Spider-Realistic | 82.1 | 84.1 |
 
-TrustSQL models are designed for **multi-turn, tool-integrated Text-to-SQL** over unknown schemas. The model explores the database schema via SQL tool calls before generating the final answer.
+The model reaches 65.8 EX on BIRD-Dev with greedy decoding and 67.7 EX with majority voting.
 
-For the full evaluation pipeline, rollout protocol, reward design, and training scripts, please refer to the GitHub repository:
+## Recommended inference setup
 
-👉 **[github.com/JaneEyre0530/TrustSQL](https://github.com/JaneEyre0530/TrustSQL)**
+This model is intended to run inside a tool-using agent loop:
 
-### Quick inference
+1. Explore database metadata and inspect relevant values.
+2. Propose only tables and columns verified by tool output.
+3. Generate and execute a candidate SQL query.
+4. Confirm the final answer, or return to exploration when evidence is insufficient.
+
+The explicit proposal checkpoint is important: it helps prevent schema hallucination and provides a boundary for the phase-aware training objective.
+
+## Loading
 
 ```python
-from transformers import AutoTokenizer, AutoModelForCausalLM
-import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
-model_name = "AIJian/TrustSQL-8B"
-tokenizer = AutoTokenizer.from_pretrained(model_name)
-model = AutoModelForCausalLM.from_pretrained(
-    model_name,
-    torch_dtype=torch.bfloat16,
-    device_map="auto"
-)
+model_id = "AIJian/TrustSQL-8B"
 
-messages = [{"role": "user", "content": "Your NL2SQL prompt here"}]
-text = tokenizer.apply_chat_template(
-    messages,
-    tokenize=False,
-    add_generation_prompt=True,
-    enable_thinking=False
+tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    torch_dtype="auto",
+    device_map="auto",
+    trust_remote_code=True,
 )
-inputs = tokenizer([text], return_tensors="pt").to(model.device)
-outputs = model.generate(**inputs, max_new_tokens=512)
-response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
-print(response)
 ```
 
-## Training Data
+For prompts, tool schemas, evaluation scripts, and training details, see `https://github.com/JaneEyre0530/TrustSQL`.
 
-The model was trained on `all_models_training_data.jsonl`, a curated dataset of ~70k Text-to-SQL examples covering diverse database schemas and natural language questions. The training data includes multi-turn SQL generation scenarios with responses from multiple model sources (DeepSeek-R1, GPT-4o-mini, GPT-4.1-mini, etc.), ensuring broad coverage of SQL patterns and query complexity.
+## Limitations
 
-## Citation
+This checkpoint was trained and evaluated with SQLite-based benchmarks. Inference requires a live and safe metadata/execution environment. Always validate generated SQL and use read-only permissions unless write access is explicitly required and controlled.
 
-If you find TRUST-SQL useful in your research, please cite our paper:
+## Citation
 
 ```bibtex
-@misc{jian2026trustsqltoolintegratedmultiturnreinforcement,
-      title={TRUST-SQL: Tool-Integrated Multi-Turn Reinforcement Learning for Text-to-SQL over Unknown Schemas}, 
-      author={Ai Jian and Xiaoyun Zhang and Wanrou Du and Jingqing Ruan and Jiangbo Pei and Weipeng Zhang and Ke Zeng and Xunliang Cai},
-      year={2026},
-      eprint={2603.16448},
-      archivePrefix={arXiv},
-      primaryClass={cs.AI},
-      url={https://arxiv.org/abs/2603.16448}, 
+@article{jian2026trustsql,
+  title   = {TRUST-SQL: Tool-Integrated Multi-Turn Reinforcement Learning for Text-to-SQL over Unknown Schemas},
+  author  = {Jian, Ai and Zhang, Xiaoyun and Du, Wanrou and Ruan, Jingqing and Pei, Jiangbo and Zhang, Weipeng and Zeng, Ke and Cai, Xunliang},
+  journal = {arXiv preprint arXiv:2603.16448},
+  year    = {2026}
 }
 ```
 
 ## License
 
-This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the Apache 2.0 License. See the `LICENSE` file for details.