Antelope-textTosql/README.md

---
library_name: transformers
tags:
- text-to-sql
- sql
- natural-language-processing
- peft
- qlora
- phi-2
- sqlite
- database
- code-generation
- question-answering
language:
- en
license: mit
base_model: microsoft/phi-2
datasets:
- spider
pipeline_tag: text-generation
---

# 🦌 Antelope Text-to-SQL

**Convert plain English questions into SQL queries instantly.**  
Lightweight, fast, and runs on CPU. No database expertise needed.

🚀 **[Try the live demo →](https://huggingface.co/spaces/AuricErgeson/Antelope-textTosql-demo)**

---

## What it does

| Question | Database | Output |
|---|---|---|
| How many employees are there? | company | `SELECT COUNT(*) FROM employees` |
| List all customers from Germany | store | `SELECT * FROM customers WHERE country = 'Germany'` |
| What is the average salary by department? | hr | `SELECT department, AVG(salary) FROM employees GROUP BY department` |

---

## Quick Start

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_id = "AuricErgeson/Antelope-textTosql"

tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
    device_map="auto",
    trust_remote_code=True
)

def generate_sql(question, db=""):
    prompt = (
        f"### Task: Convert question to SQL. Use only what the question asks. Simple questions need simple SQL.\n"
        f"### Database: {db}\n"
        f"### Question: {question}\n"
        f"### SQL:"
    )
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    with torch.no_grad():
        out = model.generate(
            **inputs,
            max_new_tokens=128,
            temperature=0.1,
            do_sample=True,
            pad_token_id=tokenizer.eos_token_id
        )
    decoded = tokenizer.decode(out[0], skip_special_tokens=True)
    return decoded.split("### SQL:")[-1].strip().split("\n")[0]

print(generate_sql("How many employees are in each department?", db="company"))
# → SELECT department, COUNT(*) FROM employees GROUP BY department
```

---

## Why use this model?

- ✅ **Small** — 2.7B params, runs on modest hardware
- ✅ **Fast** — CPU inference possible, GPU recommended
- ✅ **Open** — MIT license, use anywhere
- ✅ **No setup** — works out of the box with `transformers`
- ✅ **Cross-domain** — trained on 200+ database schemas

---

## Prompt Format

```
### Task: Convert question to SQL. Use only what the question asks. Simple questions need simple SQL.
### Database: {your_database_name}
### Question: {your_question}
### SQL:
```

---

## Via HuggingFace Inference API

```python
import requests

API_URL = "https://api-inference.huggingface.co/models/AuricErgeson/Antelope-textTosql"
headers = {"Authorization": "Bearer YOUR_HF_TOKEN"}

response = requests.post(API_URL, headers=headers, json={
    "inputs": "### Task: Convert question to SQL. Use only what the question asks. Simple questions need simple SQL.\n### Database: company\n### Question: How many employees?\n### SQL:"
})
print(response.json())
```

---

## Training Details

| Property | Value |
|---|---|
| Base model | microsoft/phi-2 (2.7B) |
| Method | QLoRA (4-bit + LoRA) |
| Dataset | Spider (7,000+ examples, 200+ databases) |
| LoRA rank | 16 |
| LoRA alpha | 32 |
| Target modules | q_proj, v_proj |
| Learning rate | 2e-4 |
| Epochs | 3 |
| Hardware | NVIDIA A100 (Google Colab) |
| Training time | ~1.5 hours |
| Adapter size | ~21MB |
| Merged model size | ~5.56GB |

---

## Limitations

- Not recommended for production databases without output validation
- Complex multi-join queries may be inaccurate
- Does not infer table/column names — provide your database name for best results

---

## Roadmap

- [x] Text-to-SQL (this model)
- [ ] Text-to-Regex (coming soon)
- [ ] Text-to-Shell (planned)

---

## Author

**Auric Ergeson Nitonde**  
📧 auricergesonnitonde@gmail.com  
🤗 [HuggingFace Profile](https://huggingface.co/AuricErgeson)

*If this model helped you, consider leaving a like ⭐ — it helps others find it.*