README.md

---
license: apache-2.0
language:
- en
- sql
tags:
- text-to-sql
- qwen
- gguf
- local-ai
- unsloth
- sql-generation
datasets:
- xlangai/spider
pipeline_tag: text-generation
base_model:
- Qwen/Qwen2.5-Coder-1.5B-Instruct
---

# 🚀 Caden SQL (1.5B) - Text-to-SQL AI

<img src="https://img.shields.io/badge/Status-Active-brightgreen" alt="Model Status" /> <img src="https://img.shields.io/badge/Size-1.5B-blue" alt="Model Size" /> <img src="https://img.shields.io/badge/Quantization-Q4__K__M-orange" alt="Quantization" /> <img src="https://img.shields.io/badge/Framework-Unsloth-purple" alt="Framework" />

**Caden** is a highly specialized, localized Artificial Intelligence designed to convert natural language questions into complex, production-ready SQL queries. It was built by fine-tuning the powerful `Qwen2.5-Coder-1.5B-Instruct` model on the extensive **Spider** dataset using Unsloth.

By utilizing 4-bit GGUF quantization, Caden is designed to be completely offline and privacy-first. You can query your private company databases locally on a standard laptop without ever sending your sensitive database schema to cloud APIs like OpenAI or Anthropic.

---

## 📊 Model Architecture & Details
* **Base Model:** `Qwen/Qwen2.5-Coder-1.5B-Instruct`
* **Parameters:** 1.5 Billion
* **Format:** GGUF (`Q4_K_M` Quantized)
* **Training Framework:** [Unsloth](https://github.com/unslothai/unsloth) (Fast LoRA adapters, successfully merged)
* **Context Length:** 32,768 tokens (Capable of ingesting massive database schemas!)

---

## 🧠 Capabilities
Unlike basic SQL generators that only output `SELECT * FROM table`, Caden has been aggressively fine-tuned to master complex relationships:
* **Advanced Joins:** Seamlessly traverses foreign keys and uses `LEFT JOIN` and `INNER JOIN` appropriately.
* **Correlated Subqueries:** Can nest queries dynamically (`WHERE salary > (SELECT AVG(salary) FROM...)`).
* **Analytical Window Functions:** Excels at `RANK()`, `ROW_NUMBER()`, and `PARTITION BY`.
* **Set Operations:** Fluidly handles `INTERSECT`, `EXCEPT`, and `UNION`.
* **Conversational Awareness:** Caden is trained to converse naturally when greeted, but strictly outputs SQL blocks when requested.

---

## 🛠️ Prompt Format (ChatML)

The model expects inputs formatted in **ChatML** with a specific structured template:

```json
[
  {
    "role": "system",
    "content": "You are Caden, an expert SQL engineer and helpful database assistant. Your primary task is to write single, accurate, and efficient SQL queries based on the given database schema and user questions."
  },
  {
    "role": "user",
    "content": "### Database Schema DDL:\nCREATE TABLE head (age INT, name VARCHAR(20));\n\n### User Request:\nFind names of heads whose age is older than 50.\n\nGenerate the SQL query that answers the user request."
  }
]
```

### Response Example:
```sql
SELECT name FROM head WHERE age > 50;
```

---

## 💻 Getting Started & Usage

### 1. Running Locally with Ollama (Recommended)
Ollama is the fastest way to run Caden on MacOS, Windows, or Linux.

1. Download the `caden-sql-1.5b-q4_k_m.gguf` file from the Files tab.
2. Create a file named `Modelfile` in the same folder with this configuration:
```dockerfile
FROM ./caden-sql-1.5b-q4_k_m.gguf
SYSTEM """You are Caden, an expert SQL engineer and helpful database assistant. Your primary task is to write single, accurate, and efficient SQL queries based on the given database schema and user questions.

Follow these strict rules when the user asks for data or a query:
1. Generate valid SQL syntax only.
2. Use ONLY the table and column names present in the provided schema DDL.
3. Carefully observe foreign key relationships when performing JOIN operations.
4. Unless explicitly requested by the user, only produce read-only queries (SELECT).
5. Provide your SQL query enclosed in a single ```sql ... ``` block.

If the user asks a general conversational question, respond conversationally and naturally without generating SQL."""
```
3. Build and register the model with Ollama:
   ```bash
   ollama create caden-sql -f Modelfile
   ```
4. Query the model in your terminal:
   ```bash
   ollama run caden-sql
   ```

### 2. Running via Hugging Face Transformers (Python)

If you are using the unquantized or merged weights directly via Python:

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

model_name = "loftytechlabsdev/Caden-SQL-1.5B"

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

# Format the message using ChatML
messages = [
    {
        "role": "system",
        "content": "You are Caden, an expert SQL engineer and helpful database assistant. Your primary task is to write single, accurate, and efficient SQL queries based on the given database schema and user questions."
    },
    {
        "role": "user",
        "content": "### Database Schema DDL:\nCREATE TABLE customers (id INT PRIMARY KEY, name VARCHAR(50), city VARCHAR(50));\n\n### User Request:\nHow many customers are from London?\n\nGenerate the SQL query that answers the user request."
    }
]

prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer([prompt], return_tensors="pt").to(model.device)

outputs = model.generate(**inputs, max_new_tokens=256, use_cache=True)
response = tokenizer.decode(outputs[0][len(inputs.input_ids[0]):], skip_special_tokens=True)
print(response)
```

---

## 📈 Training Details & Hyperparameters

*   **Base Model**: `unsloth/Qwen2.5-Coder-1.5B-Instruct`
*   **Method**: QLoRA (4-bit quantization, rank `r = 16`, `lora_alpha = 16`)
*   **Dataset**: `xlangai/spider` / `philikai/SQL_Spider_DDL` (containing 10,000+ text-to-SQL alignment examples)
*   **Optimizer**: `adamw_8bit`
*   **Learning Rate**: `2e-4`
*   **Scheduler**: `linear`
*   **Weight Decay**: `0.01`
*   **Batch Size**: 4 per device, 4 gradient accumulation steps (Effective batch size = 16)
*   **Training Steps**: 200 SFT steps (tuned to prevent overfitting while maintaining high zero-shot SQL validation accuracy)

---

# 📝 Release Notes (v1.0)

- **Initial Release:** First highly capable 1.5B-parameter SQL generation model.
- **Focus:** Mastered Spider dataset benchmarks, including:
  - Correlated Subqueries
  - Set Operations
  - Window Functions
- **Future Roadmap (v2.0):** Plans to scale up to a 7B-parameter model and support more complex real-world database schemas and advanced SQL query patterns.

---

## ⚠️ Limitations & Bias

*   **Database Engine**: Primarily trained and evaluated on general SQLite/ANSI SQL. Syntaxes specific to PostgreSQL, MSSQL, or Oracle may require small manual adjustments or specialized fine-tuning.
*   **Query Complexity**: Excellent for joins, subqueries, group by, and aggregate operations. Highly complex recursive CTEs or vendor-specific window functions may occasionally require manual corrections.

---

## 📜 License

This project is released under the **Apache 2.0** License, adhering to the base model guidelines of the Qwen series.