README.md

---
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
tags:
  - text-to-sql
  - sql
  - unknown-schema
  - tool-use
  - reinforcement-learning
  - qwen3
base_model: Qwen/Qwen3-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)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

## Overview

**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.

## Model details

- 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) |

## 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 |

The model reaches 65.8 EX on BIRD-Dev with greedy decoding and 67.7 EX with majority voting.

## Recommended inference setup

This model is intended to run inside a tool-using agent loop:

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 AutoModelForCausalLM, AutoTokenizer

model_id = "AIJian/TrustSQL-8B"

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,
)
```

For prompts, tool schemas, evaluation scripts, and training details, see `https://github.com/JaneEyre0530/TrustSQL`.

## Limitations

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.

## Citation

```bibtex
@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` file for details.