Update README.md

README.md

@@ -1,22 +1,91 @@
 ---
-base_model: unsloth/Qwen2.5-0.5B-Instruct
-tags:
-- text-generation-inference
-- transformers
-- unsloth
-- qwen2
-- trl
+base_model: Qwen/Qwen2.5-0.5B-Instruct
+library_name: peft
 license: apache-2.0
 language:
 - en
+pipeline_tag: text-generation
+tags:
+- text-to-sql
+- sql
+- grpo
+- reinforcement-learning
+- lora
+- trl
+- unsloth
 ---
 
-# Uploaded finetuned model
+# SQL-GRPO 0.5B
+
+A LoRA adapter for **Qwen2.5-0.5B-Instruct**, trained with **GRPO** (Group Relative Policy Optimization) to turn natural-language questions into SQLite queries. The reward comes from **executing the generated SQL** against the real database: no human-labeled feedback, the database is the judge.
+
+🚀 **[Live demo](https://huggingface.co/spaces/bimal2004/sql-grpo-demo)** (uses the 1.5B version) · 💻 **[Code](https://github.com/bimal1023/sql-grpo)** · 🔗 **[1.5B version](https://huggingface.co/bimal2004/sql-grpo-1.5b)**
+
+## Results
+
+Spider dev set (1,034 questions on databases not seen during training), execution accuracy:
+
+| Model | Accuracy | Valid SQL | Correct format |
+| --- | --- | --- | --- |
+| Qwen2.5-0.5B-Instruct (untrained) | 18.18% | 35.40% | 66.73% |
+| **This model (GRPO)** | **41.68%** | **73.21%** | **99.81%** |
+| Qwen2.5-1.5B-Instruct (untrained, for reference) | 40.72% | 58.41% | 76.89% |
+| gpt-4.1-mini (prompted, for reference) | 74.37% | 98.74% | 100.00% |
+
+GRPO more than doubled accuracy (2.3×); the trained 0.5B model outperforms the untrained 1.5B model, which is 3× its size. The gain isn't only formatting: among well-formatted answers, correctness rose from about 27% to about 42%.
+
+## How to use
+
+```python
+import re
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct", torch_dtype="auto")
+model = PeftModel.from_pretrained(base, "bimal2004/sql-grpo-0.5b")
+tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")
+
+schema = """CREATE TABLE singer (
+  Singer_ID int, Name text, Country text, Age int,
+  PRIMARY KEY (Singer_ID)
+)"""
+question = "How many singers are from France?"
+
+messages = [
+    {"role": "system", "content": (
+        "You are a SQLite expert. Given a database schema and a question, "
+        "write one SQLite query that answers it. "
+        "Put only the query inside <sql></sql> tags.")},
+    {"role": "user", "content": f"Schema:\n{schema}\n\nQuestion: {question}"},
+]
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(text, return_tensors="pt").to(model.device)
+out = model.generate(**inputs, max_new_tokens=256, do_sample=False)
+answer = tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
+
+sql = re.search(r"<sql>(.*?)</sql>", answer, re.DOTALL).group(1).strip()
+print(sql)
+```
+
+**Prompt format matters:** the model was trained with exactly this system prompt, with the schema given as `CREATE TABLE` statements, and answers inside `<sql></sql>` tags.
+
+At 0.5B parameters, this model is small enough to run on a laptop CPU.
+
+## Training details
+
+- **Method:** GRPO via Hugging Face TRL `GRPOTrainer` + Unsloth, LoRA rank 32 (about 3.4% of parameters trained)
+- **Data:** Spider train split (6,289 questions after filtering very long schemas)
+- **Reward:** +1.0 if the query returns the same rows as the gold SQL, +0.2 if it runs without error, +0.1 for correct `<sql>` formatting, −0.1 for overly long output. Queries run on a read-only connection with a 2-second timeout.
+- **Setup:** 400 steps (~2 hours), 8 sampled answers per question, learning rate 5e-6, on a single free Kaggle T4 GPU
+
+## Limitations
 
-- **Developed by:** bimal2004
-- **License:** apache-2.0
-- **Finetuned from model :** unsloth/Qwen2.5-0.5B-Instruct
+- Trained and evaluated only on **Spider** (SQLite); performance on other SQL dialects or very large real-world schemas is untested.
+- Accuracy is about 42%: most complex questions (JOINs, nested queries) are still answered incorrectly. For better accuracy, use the [1.5B version](https://huggingface.co/bimal2004/sql-grpo-1.5b) (57.74%).
+- Common errors include referencing columns that don't exist and missing JOINs.
+- Some correct answers on borderline questions can flip under different numerical precision or batching. Evaluate on many questions, not single examples.
+- Always review generated SQL before running it on important data.
 
-This qwen2 model was trained 2x faster with [Unsloth](https://github.com/unslothai/unsloth)
+## Credits
 
-[<img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" width="200"/>](https://github.com/unslothai/unsloth)
+Built by [Bimal Kumal](https://bimalkumal7.com.np). Base model: [Qwen2.5-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct). Data: [Spider](https://github.com/taoyds/spider) (Yu et al., 2018).