Model Card for SQL2NL

SQL2NL is a fine-tune of Llama 3.2 3B Instruct that translates complex analytical SQL — CTEs, window functions, multi-table JOINs, cohort/funnel analysis — into concise, executive-level business logic descriptions, so non-technical stakeholders get the "what and why" of a query without reading a line of code.

Model Details

Model Description

SQL2NL converts SQL queries into plain-English explanations of business intent. It identifies key metrics, dimensions, filters, and time windows; describes JOINs as business relationships ("customers linked to their orders"); interprets CTEs as logical analytical steps; and renders window functions as comparative analytics ("ranking customers by lifetime value"). Output is restricted to executive-friendly language with no SQL jargon.

• Developed by: Gaurav Shinde (ShindeGaurav-2207)
• Funded by: Self-funded
• Shared by: Gaurav Shinde
• Model type: Decoder-only causal language model (LlamaForCausalLM) specialized for SQL-to-natural-language explanation
• Language(s) (NLP): English
• License: MIT
• Finetuned from model: meta-llama/Llama-3.2-3B-Instruct

Model Sources

• Repository: https://github.com/ShindeGaurav-2207/SQL2NL
• Paper: N/A
• Demo: FastAPI service shipped with the repository (uvicorn src.app:app)

Uses

Direct Use

Prompt the model with a SQL query using the Llama 3 chat template it was fine-tuned on:

<|begin_of_text|><|start_header_id|>system<|end_header_id|>

Translate the SQL query into an executive-level business logic description.
No SQL jargon. Under 150 words.<|eot_id|><|start_header_id|>user<|end_header_id|>

SQL Query:
```sql
WITH customer_revenue AS (
  SELECT c.customer_id, SUM(o.total_amount) AS ltv
  FROM customers c JOIN orders o ON c.customer_id = o.customer_id
  WHERE o.order_date >= '2024-01-01'
  GROUP BY c.customer_id
)
SELECT customer_id, RANK() OVER (ORDER BY ltv DESC) AS rnk FROM customer_revenue

Business Logic Description:<|eot_id|><|start_header_id|>assistant<|end_header_id|>

Stop tokens: `<|eot_id|>`, `<|end_of_text|>`. For best fidelity use the original training system prompt ("*You are a SQL-to-plain-language translator…*") — see the training notebook in the repository. Typical output style: *"How many heads of the departments are older than 56?"*

### Downstream Use

<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->

Ships as part of the [SQL2NL project](https://github.com/ShindeGaurav-2207/SQL2NL): a `ModelManager` singleton with automatic Hugging Face Hub download, a `llama-cpp-python` inference engine, a FastAPI endpoint (`POST /v1/translate`) with Pydantic contracts, an Ollama `Modelfile`, and a quantitative evaluation harness (`eval/evaluate.py`).

### Out-of-Scope Use

<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->

The model does not generate SQL, optimize queries, execute anything, or know actual data values. It must not be used as an audited specification of query behavior — descriptions are informed guesses about intent that should be validated against execution results. DDL/DML translation and non-English input are out of distribution.

## Bias, Risks, and Limitations

<!-- This section is meant to convey both technical and sociotechnical limitations. -->

- English only; trained on analytical SELECT queries.
- May hallucinate table/column semantics when names are ambiguous (e.g., guessing that `status = 'X'` implies a specific business state).
- Inherits biases of the Llama 3.2 base model.
- Window-function and nested-CTE descriptions are strongest; very long (>200-line) queries may exceed reliable attention.
- Explanations reflect plausible intent, not guaranteed semantics.

### Recommendations

<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->

Users (both direct and downstream) should treat outputs as documentation drafts, not ground truth, and verify against actual query behavior before acting on them.

## How to Get Started with the Model

Use the code below to get started with the model.

```python
from transformers import pipeline
import torch

pipe = pipeline(
    "text-generation",
    model="ShindeGaurav-2207/SQL2NL",
    torch_dtype=torch.float16,
    device_map="auto",
)

messages = [
    {"role": "system", "content": "Translate the SQL query into executive-level business logic. No SQL jargon."},
    {"role": "user", "content": f"SQL Query:\n```sql\n{sql}\n```\n\nBusiness Logic Description:"},
]

print(pipe(messages, max_new_tokens=256)[0]["generated_text"][-1]["content"])

Training Details

Training Data

A curated set of 1,500 SQL → plain-language explanation conversations, generated via TuneKit and embedded in the training notebook (notebooks/finetune_llama32_sql_explanations.ipynb). Every example is a (system, user, assistant) triplet:

• System: a fixed "SQL-to-plain-language translator" instruction — phrase the explanation the way a business user would state the intent (e.g., "How many heads of the departments are older than 56?"), optionally add one short technical clause for non-obvious joins/filters/aggregations, never fabricate an explanation for invalid SQL, and never repeat the query back.
• User: a SQL query with an "Explain this SQL query in simple business terms" wrapper.
• Assistant: the natural-language business explanation.

Training Procedure

Fine-tuned with Unsloth (v2026.8.19) using QLoRA: the base model is loaded in 4-bit quantization (load_in_4bit=True, max sequence length 2048) while LoRA adapters train. Adapters were subsequently merged into the base weights and exported as merged 16-bit safetensors (~6.4 GB) plus a Q4_K_M GGUF.

Preprocessing

Conversations rendered with the tokenizer's Llama 3 chat template via tokenizer.apply_chat_template(...) into a single text field; packing=False; no additional filtering.

Training Hyperparameters

• Training regime: fp16/bf16 mixed precision (auto-selected by Unsloth based on GPU support)
• LoRA config: rank 16, alpha 16, dropout 0, bias none, target modules [q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj] (all attention + MLP projections)
• Epochs / LR / batch size: 3 epochs; per-device batch size 2 × gradient accumulation 4 (effective batch 8); learning rate 2e-4 with linear scheduler, 5 warmup steps
• Optimizer: AdamW 8-bit, weight decay 0.01, seed 42
• Checkpointing: save once per epoch (limit 2), logging every 10 steps

Speeds, Sizes, Times

Trained on a Kaggle cloud notebook (NVIDIA T4 class GPU). Final artifacts: LoRA adapter, merged 16-bit checkpoint (6.4 GB across two safetensors shards), and Q4_K_M GGUF (2 GB). Peak GPU memory and exact wall-clock time: [More Information Needed].

Evaluation

Testing Data, Factors & Metrics

Testing Data

8 held-out analytical queries covering CTEs, window functions, multi-JOIN aggregations, cohort retention, funnel analysis, moving averages, and percentile breakdowns (eval/eval_dataset.json in the repository).

Factors

Query pattern category (CTE-heavy, window-function-heavy, JOIN-heavy).

Metrics

• Keyword coverage: fraction of expected business terms present in the output — measures terminology faithfulness.
• Semantic similarity: cosine similarity between output and gold reference embeddings (sentence-transformers/all-MiniLM-L6-v2) — measures meaning preservation.
• Latency: end-to-end inference time in milliseconds.

Results

Evaluated on the full 8-query benchmark (GTX 1650, greedy decoding, transformers backend). References are phrased in the same interrogative register the model was fine-tuned to produce:

Metric	Score
Pass rate (cov ≥ 50% ∧ sim ≥ 70%)	75% (6/8)
Keyword coverage	65.1% avg
Semantic similarity	0.774 avg
Avg latency	~700 s/sample (CPU-offloaded FP16; GGUF/llama.cpp path is far faster)

Per-sample similarity: 0.84 / 0.71 / 0.85 / 0.74 / 0.78 / 0.76 / 0.83 / 0.68. The two remaining failures (eval_006 moving-average query, eval_008 funnel query) produce correct but terse descriptions that omit some expected business terms — a genuine verbosity gap rather than misunderstanding.

Summary

The model reliably translates analytical SQL into faithful business-language descriptions matching its trained question-style register; 6 of 8 complex analytical queries pass both faithfulness metrics outright.

Model Examination

[More Information Needed]

Environmental Impact

Carbon emissions can be estimated using the Machine Learning Impact calculator presented in Lacoste et al. (2019).

• Hardware Type: NVIDIA T4 (Kaggle notebook GPU)
• Hours used: <1 GPU-hour (3B-parameter QLoRA, 1,500 examples, 3 epochs)
• Cloud Provider: Kaggle
• Compute Region: [More Information Needed]
• Carbon Emitted: [More Information Needed]

Technical Specifications

Model Architecture and Objective

LlamaForCausalLM — 3.21B parameters, 28 layers, hidden size 3072, GQA (24 query heads / 8 KV heads), SwiGLU MLP (intermediate 8192), RoPE (theta 500000, llama3 scaling, max positions 131072), vocabulary 128,256. Fine-tuning objective: next-token prediction on (system, SQL query) -> business logic pairs in the Llama 3 chat format (<|start_header_id|> … <|eot_id|>).

Compute Infrastructure

Hardware

Kaggle single-GPU notebook (fine-tuning); CPU or NVIDIA GPU via llama.cpp n_gpu_layers (inference).

Software

Unsloth v2026.8.19, TRL SFTTrainer, Hugging Face datasets, PyTorch on the Kaggle Docker image (transformers 5.5.0); llama-cpp-python and FastAPI for serving.

Citation

BibTeX:

@misc{shinde2026sql2nl,
  author       = {Shinde, Gaurav},
  title        = {SQL2NL: Fine-tuned Llama 3.2 3B for SQL-to-Business-Logic Translation},
  year         = {2026},
  howpublished = {\url{https://huggingface.co/ShindeGaurav-2207/SQL2NL}}
}

APA:

Shinde, G. (2026). SQL2NL: Fine-tuned Llama 3.2 3B for SQL-to-business-logic translation [Computer software]. Hugging Face. https://huggingface.co/ShindeGaurav-2207/SQL2NL

Glossary

• CTE: Common Table Expression — a named subquery defined with WITH, read here as a logical analytical step.
• Window function: An aggregate computed across related rows (e.g., RANK() OVER (...)), explained as comparative analytics.
• Keyword coverage: Share of expected business terms appearing in the generated explanation.

More Information

See the project repository for the API server, GGUF/Ollama deployment path, Docker setup, and benchmark harness.

Model Card Authors

Gaurav Shinde

Model Card Contact

GitHub: ShindeGaurav-2207