Update README.md

README.md

@@ -1,62 +1,157 @@
 ---
 base_model: Qwen/Qwen2.5-1.5B-Instruct
 library_name: peft
-model_name: v1
+license: mit
+datasets:
+- b-mc2/sql-create-context
+language:
+- en
+- de
 tags:
-- base_model:adapter:Qwen/Qwen2.5-1.5B-Instruct
+- text-to-sql
+- qwen
+- qwen2.5
+- peft
 - lora
-- sft
-- transformers
-- trl
-licence: license
+- qlora
+- generated_from_trainer
+- code-generation
 pipeline_tag: text-generation
+widget:
+- text: |
+    <|im_start|>system
+    You are a SQL expert.<|im_end|>
+    <|im_start|>user
+    CREATE TABLE employees (id INT, name VARCHAR, department VARCHAR, salary INT)
+    Question: List the names of employees in the Sales department.<|im_end|>
+    <|im_start|>assistant
 ---
 
-# Model Card for v1
+# Qwen 2.5 (1.5B) - SQL Assistant Production Adapter
 
-This model is a fine-tuned version of [Qwen/Qwen2.5-1.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct).
-It has been trained using [TRL](https://github.com/huggingface/trl).
+[![Hugging Face Space](https://img.shields.io/badge/🤗%20Hugging%20Face-Live%20Demo-yellow)](https://huggingface.co/spaces/manuelaschrittwieser/SQL-Assistant-Prod)
+[<img src="https://raw.githubusercontent.com/wandb/assets/main/wandb-github-badge-28.svg" alt="Visualize in Weights & Biases" width="150" height="24"/>](https://wandb.ai/manuelaschrittwieser99-neuralstack-ms/sql-assistant/runs/8ftaccqr) 
+![License](https://img.shields.io/badge/License-MIT-green)
+
+## 📑 Model Overview
+
+**Qwen2.5-SQL-Assistant-Prod** is a specialized parameter-efficient fine-tune (PEFT) of the [Qwen 2.5 1.5B Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct) large language model.
+
+This model is engineered to function as a technical assistant capable of translating natural language questions into syntactically correct SQL queries. It relies on a provided database schema (context) to ensure column and table names are hallucination-free.
+
+### Key Capabilities
+*   **Context-Aware Generation:** Adheres strictly to the `CREATE TABLE` schema provided in the prompt.
+*   **Low-Latency Inference:** Optimized for consumer hardware (CPU friendly) due to the lightweight 1.5B parameter count and LoRA adapter architecture.
+*   **Agentic Integration:** Designed to serve as the reasoning engine for autonomous SQL agents.
+
+---
+
+## 📊 Training Telemetry & Metrics
+
+The training process was tracked and visualized using **Weights & Biases** to ensure stability and convergence.
+
+**[👉 Click here to view the full W&B Training Run / Charts](https://wandb.ai/manuelaschrittwieser99-neuralstack-ms/sql-assistant/runs/8ftaccqr)**
+
+*   **Training Loss:** Monitored to ensure no overfitting on the SQL syntax patterns.
+*   **Hardware:** Trained on NVIDIA T4 GPU.
+*   **Framework:** Hugging Face `trl` (SFTTrainer) + `peft`.
+
+---
+
+## 🛠️ Technical Specifications
+
+### Architecture
+*   **Base Model:** `Qwen/Qwen2.5-1.5B-Instruct`
+*   **Adaptation Method:** QLoRA (Quantized Low-Rank Adaptation)
+*   **Quantization:** 4-bit NormalFloat (NF4) via `bitsandbytes`
+
+### Hyperparameters
+| Parameter | Value | Description |
+| :--- | :--- | :--- |
+| **LoRA Rank (r)** | 16 | Dimension of the low-rank update matrices. |
+| **LoRA Alpha** | 16 | Scaling factor for LoRA. |
+| **Dropout** | 0.05 | Regularization to prevent overfitting. |
+| **Target Modules** | `q_proj`, `k_proj`, `v_proj`, `o_proj` | Layers targeted for adaptation. |
+| **Learning Rate** | 2e-4 | Initial learning rate. |
+| **Batch Size** | 4 | Per-device training batch size. |
+| **Epochs** | 1 | Single pass over the instruct dataset. |
 
-## Quick start
+### Dataset
+The model was fine-tuned on **[b-mc2/sql-create-context](https://huggingface.co/datasets/b-mc2/sql-create-context)**, a dataset containing pairs of:
+1.  **Context:** SQL Schema definition (`CREATE TABLE...`).
+2.  **Question:** Natural language inquiry.
+3.  **Answer:** Gold-standard SQL query.
 
-```python
-from transformers import pipeline
+---
+
+## 💻 Usage Instructions
 
-question = "If you had a time machine, but could only go to the past or the future once and never return, which would you choose and why?"
-generator = pipeline("text-generation", model="None", device="cuda")
-output = generator([{"role": "user", "content": question}], max_new_tokens=128, return_full_text=False)[0]
-print(output["generated_text"])
+This model is an **adapter**. You must load the base Qwen model first and then attach these adapter weights.
+
+### Prerequisite
+```bash
+pip install transformers peft torch
 ```
 
-## Training procedure
+## Inference Code
 
-[<img src="https://raw.githubusercontent.com/wandb/assets/main/wandb-github-badge-28.svg" alt="Visualize in Weights & Biases" width="150" height="24"/>](https://wandb.ai/manuelaschrittwieser99-neuralstack-ms/sql-assistant/runs/8ftaccqr) 
+```Python
+import torch
+from peft import PeftModel
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# 1. Configuration
+BASE_MODEL_ID = "Qwen/Qwen2.5-1.5B-Instruct"
+ADAPTER_ID = "manuelaschrittwieser/Qwen2.5-SQL-Assistant-Prod"
+
+# 2. Load Base Model (Load in 4-bit for efficiency if using GPU, or float32 for CPU)
+base_model = AutoModelForCausalLM.from_pretrained(
+    BASE_MODEL_ID,
+    device_map="auto",
+    torch_dtype=torch.float16
+)
+
+# 3. Load the Adapter
+model = PeftModel.from_pretrained(base_model, ADAPTER_ID)
+tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL_ID)
+
+# 4. Define Context & Question
+schema = "CREATE TABLE users (id INT, name VARCHAR, age INT, city VARCHAR)"
+question = "How many users live in Paris?"
 
+# 5. Format Prompt (Qwen Chat Template)
+messages = [
+    {"role": "system", "content": "You are a SQL expert."},
+    {"role": "user", "content": f"{schema}\nQuestion: {question}"}
+]
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
 
-This model was trained with SFT.
+# 6. Generate
+inputs = tokenizer(text, return_tensors="pt").to(model.device)
+with torch.no_grad():
+    outputs = model.generate(**inputs, max_new_tokens=100)
 
-### Framework versions
+# 7. Decode Output
+print(tokenizer.decode(outputs[0], skip_special_tokens=True).split("assistant")[-1].strip())
+
+```
+
+---
+
+## ⚠️ Limitations
+
+* **Prompt Sensitivity:** The model performs best when the database schema is explicitly provided in the system or user prompt.
+* **Complex Logic:** While proficient at `JOIN`, `GROUP BY`, and `WHERE` clauses, highly complex nested sub-queries or database-specific dialect functions (like PostgreSQL JSONB operators) may not be generated correctly.
+* **Security:** This model generates SQL code. **Always** sanitize and review generated queries before executing them on a production database to prevent SQL injection vulnerabilities.
+
+---
 
-- PEFT 0.18.0
-- TRL: 0.26.2
-- Transformers: 4.57.3
-- Pytorch: 2.9.0+cu126
-- Datasets: 4.0.0
-- Tokenizers: 0.22.1
+## 📜 Framework Versions
 
-## Citations
+* **PEFT:** 0.18.0
+* **Transformers:** 4.37.0+
+* **TRL:** 0.26.2
+* **PyTorch:** 2.1.0+
 
 
 
-Cite TRL as:
-    
-```bibtex
-@misc{vonwerra2022trl,
-	title        = {{TRL: Transformer Reinforcement Learning}},
-	author       = {Leandro von Werra and Younes Belkada and Lewis Tunstall and Edward Beeching and Tristan Thrush and Nathan Lambert and Shengyi Huang and Kashif Rasul and Quentin Gallou{\'e}dec},
-	year         = 2020,
-	journal      = {GitHub repository},
-	publisher    = {GitHub},
-	howpublished = {\url{https://github.com/huggingface/trl}}
-}
-```