loftytechlabsdev/Caden-SQL-1.5B-GGUF

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

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 (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:

[
  {
    "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:

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:

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:

   ollama create caden-sql -f Modelfile
   

4. Query the model in your terminal:

   ollama run caden-sql
   

2. Running via Hugging Face Transformers (Python)

If you are using the unquantized or merged weights directly via 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.