ShindeGaurav-2207/SQL2NL

Model Card for SQL2NL

<!-- Provide a quick summary of what the model is/does. -->

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

<!-- Provide a longer summary of what this model is. -->

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

<!-- Provide the basic links for the model. -->

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

Uses

<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->

Direct Use

<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->

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:

WITH customerrevenue AS ( SELECT c.customerid, SUM(o.totalamount) AS ltv FROM customers c JOIN orders o ON c.customerid = o.customerid WHERE o.orderdate >= '2024-01-01' GROUP BY c.customerid ) SELECT customerid, 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: 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.

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

<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->

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

<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the 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 Q4KM 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) <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
• —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

<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->

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 Q4KM GGUF (~2 GB). Peak GPU memory and exact wall-clock time: [More Information Needed].

Evaluation

<!-- This section describes the evaluation protocols and provides the results. -->

Testing Data, Factors & Metrics

Testing Data

<!-- This should link to a Dataset Card if possible. -->

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

<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->

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

Metrics

<!-- These are the evaluation metrics being used, ideally with a description of why. -->

• —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:

Per-sample similarity: 0.84 / 0.71 / 0.85 / 0.74 / 0.78 / 0.76 / 0.83 / 0.68. The two remaining failures (eval006 moving-average query, eval008 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

<!-- Relevant interpretability work for the model goes here -->

[More Information Needed]

Environmental Impact

<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->

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

<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->

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

<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->

• —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