⚡ Text-to-SQL AI Generator

Translate Natural Language Questions into Precise SQL Queries using Fine-Tuned LLMs

---

📌 Overview

Text-to-SQL AI Generator is an end-to-end open-source system that converts natural language questions into syntactically valid and schema-accurate SQL queries.

By fine-tuning Qwen/Qwen2.5-Coder-1.5B on the comprehensive b-mc2/sql-create-context dataset (78,000+ examples) using Unsloth and parameter-efficient LoRA (Low-Rank Adaptation), this model achieves fast inference and high query generation accuracy while remaining lightweight enough to deploy on free-tier CPU or ZeroGPU cloud instances.

flowchart LR
    A[Database Schema / DDL] --> C[ChatML Prompt Formatter]
    B[Natural Language Question] --> C
    C --> D[Fine-Tuned Qwen2.5-Coder + LoRA]
    D --> E[Post-Processing & Cleaner]
    E --> F[Ready-to-Execute SQL Query]

Loading

---

✨ Key Features

• Schema-Aware Query Generation: Understands complex CREATE TABLE DDL statements, primary/foreign keys, and column constraints.
• Lightweight & Efficient: Powered by Qwen 2.5 Coder (1.5B) fine-tuned with 4-bit quantization and LoRA, enabling fast execution on consumer GPUs and free cloud tiers.
• Interactive Web Interface: Built with Gradio featuring real-time syntax-highlighted SQL output, temperature/token tuning, and preloaded database examples.
• Universal Hardware Support: Automatically adapts to NVIDIA CUDA GPUs, Apple Silicon / MPS, and standard CPUs.
• 1-Click Free Cloud Deployment: Fully compatible with Hugging Face Spaces (Free CPU & ZeroGPU), Render, and local environments.

---

🧠 Model & Training Specifications

Parameter	Configuration / Value
Base Model	Qwen/Qwen2.5-Coder-1.5B
Fine-Tuning Framework	Unsloth AI
Quantization	4-bit QLoRA (NF4)
LoRA Rank ($r$)	16
LoRA Alpha ($\alpha$)	32
Target Modules	q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
Max Sequence Length	2048 tokens
Dataset	b-mc2/sql-create-context (78,577 samples)
Prompt Format	ChatML (`<

---

📂 Repository Structure

├── Text2SQL_Fine_Tuning_Unsloth.ipynb   # Complete training, LoRA setup & evaluation notebook
├── app.py                              # Standalone Gradio web application (CPU/ZeroGPU ready)
├── requirements.txt                    # Production & deployment dependencies
├── my_unsloth_sql_model.zip            # Exported LoRA adapter weights and tokenizer configs
├── README.md                           # Project documentation & HF Space configuration
└── qwen2.5-coder-1.5b-sql-lora-unsloth/ # Extracted adapter weights (auto-extracted by app.py)
    ├── adapter_config.json
    ├── adapter_model.safetensors
    ├── tokenizer.json
    └── tokenizer_config.json

---

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/<your-username>/text-to-sql-ai.git
cd text-to-sql-ai

2. Set Up Virtual Environment & Install Dependencies

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate

# Install requirements
pip install -r requirements.txt

3. Launch the Web Application

python app.py

Open your browser and navigate to http://127.0.0.1:7860.

---

🌐 Deploy to Hugging Face Spaces (100% Free Hosting)

You can host this application permanently on Hugging Face Spaces:

1. Create a Space: Go to huggingface.co/new-space.
2. Select Settings:
   • SDK: Gradio
   • Hardware: CPU basic · 2 vCPU · 16GB (Free) or ZeroGPU
   • Visibility: Public
3. Upload Files:
   • Push this repository or upload app.py, requirements.txt, README.md, and my_unsloth_sql_model.zip.
4. Live URL: Hugging Face will automatically build and serve your app 24/7 at: https://huggingface.co/spaces/<your-username>/<your-space-name>

---

💡 Example Queries

Example 1: Human Resources Analytics

• Schema (DDL):

  CREATE TABLE employees (
      id INT PRIMARY KEY,
      name VARCHAR(50),
      department VARCHAR(50),
      salary INT,
      hire_date DATE
  );

• Question: "What is the average salary of employees in the Engineering department?"
• Generated SQL:

  SELECT AVG(salary) FROM employees WHERE department = 'Engineering';

Example 2: E-Commerce Multi-Table Filter

• Schema (DDL):

  CREATE TABLE customers (customer_id INT, country VARCHAR(50));
  CREATE TABLE orders (order_id INT, customer_id INT, total_amount DECIMAL(10,2), order_date DATE);

• Question: "Find the total order amount for customers from Canada ordered in 2023."
• Generated SQL:

  SELECT SUM(T2.total_amount) FROM customers AS T1 JOIN orders AS T2 ON T1.customer_id = T2.customer_id WHERE T1.country = 'Canada' AND strftime('%Y', T2.order_date) = '2023';

---

🔬 Training Pipeline

To reproduce the training or train on a custom dataset:

1. Open Text2SQL_Fine_Tuning_Unsloth.ipynb in Google Colab (Free T4 GPU).
2. Run cells sequentially:
   • Environment setup & Unsloth installation
   • Base model loading in 4-bit with LoRA target injection
   • Dataset tokenization and ChatML formatting
   • SFTTrainer configuration & training loop
   • Inference verification & export of LoRA adapters to .zip

---

📄 License

Distributed under the Apache License 2.0. See LICENSE for more information.

---

🤝 Contributing & Acknowledgments

• Built with Unsloth AI for ultra-fast LLM fine-tuning.
• Base architecture by Qwen Team (Alibaba Cloud).
• Dataset curated by b-mc2.