lfed-qwen2.5-coder-14b-sql-lora

LFED SQL Assistant — Qwen2.5-Coder-14B-LoRA

A LoRA adapter that turns plain-English school-data questions into read-only DuckDB SQL queries. Built for the Local First Education Data Framework (LFED), a local-first analytics assistant for school administrators.

• Live demo: https://huggingface.co/spaces/build-small-hackathon/Kasualdad_LFED
• GGUF (local/llama.cpp): https://huggingface.co/build-small-hackathon/lfed-qwen2.5-coder-14b-sql-gguf
• Project: https://huggingface.co/spaces/build-small-hackathon/Kasualdad_LFED

---

Model Details

• Developer: build-small-hackathon (HF Build Small Hackathon, Chapter One: Backyard AI)
• Base model: unsloth/qwen2.5-coder-14b-instruct-bnb-4bit
• Model type: Causal LM, text-to-SQL, instruction-tuned
• Language: English (questions and SQL)
• License: Apache 2.0
• Fine-tuning method: Unsloth QLoRA (r=32, α=32, target modules q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj)
• Training data: 27,859 synthetic NL→SQL pairs over a 5-table education schema
• Adapter size: ~551 MB
• Framework versions: PEFT 0.19.1, transformers, Unsloth, TRL

---

Intended Use

This adapter is designed for a single downstream task: converting natural-language questions about school data into safe, read-only SQL.

Direct use

• Drop the adapter onto the base model for inference in the LFED Gradio app.
• Run locally with the matching GGUF or with transformers + PEFT.

Suitable questions

• "How many students were chronically absent at Lincoln Elementary in 2023-2024?"
• "What is the suspension rate by race/ethnicity at Washington Middle?"
• "Show the average GPA for English learners vs non-English learners."
• "Which school has the highest enrollment growth since 2021?"

Out-of-scope use

• Not a general chatbot or coding assistant.
• Not trained on real student PII; the demo uses synthetic seed data only.
• Not suitable for arbitrary SQL dialects beyond DuckDB-compatible queries.
• Should not be used for write operations; the execution guard allows only SELECT statements.

---

Training Details

Training data

• Source: synthetic data generated from hand-written templates, augmented with Gretel, and rephrased for natural-language variety.
• Schema: 5 tables — students, enrollment, attendance, discipline, grades.
• Coverage: single-table aggregations, joins, filtering by school/year/grade, subgroup comparisons, ranking, and simple rates/percentages.
• Size: 27,859 question→SQL pairs.
• Format: each example contains a question and a sql field.
• Data generation scripts: modal_train/generate_synthetic_v2.py, modal_train/augment_gretel.py, modal_train/rephrase_pairs.py in the project repo.

Training procedure

Training completed on 2026-06-10.

Outputs

---

Evaluation

Approach

Evaluation is currently manual: a bank of 15 real-world-style queries spanning attendance, discipline, grades, enrollment, and equity comparisons is run through the LFED demo UI. Each query is scored on:

1. Correctness — does the answer match the expected aggregation/join?
2. SQL quality — is the generated SQL valid, safe, and readable?
3. UX — is the summary + table useful?
4. Latency — does the query complete within a reasonable time?

Known limitations

• The model is fine-tuned on synthetic data; real-world schema variations require additional prompting or fine-tuning.
• It occasionally needs explicit school name and school year in the question to produce the most reliable query.
• Complex multi-step reasoning (e.g., "students who improved GPA across consecutive years") can be brittle.
• Percentage/rate formatting is handled by the downstream app, not the model; the model may return either 0–1 proportions or already-scaled percentages.
• No formal academic benchmark evaluation has been run.

---

How to Use

With transformers + PEFT (HF Space path)

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

base_id = "unsloth/qwen2.5-coder-14b-instruct-bnb-4bit"
adapter_id = "build-small-hackathon/lfed-qwen2.5-coder-14b-sql-lora"

tokenizer = AutoTokenizer.from_pretrained(base_id)
model = AutoModelForCausalLM.from_pretrained(
    base_id,
    torch_dtype=torch.float16,
    device_map="auto",
)
model = PeftModel.from_pretrained(model, adapter_id, torch_device="cpu")

prompt = """You are an assistant that converts school-data questions into DuckDB SQL.
Schema:
- students(student_id, school_name, grade_level, gender, race_ethnicity, english_learner, special_education, economically_disadvantaged)
- attendance(student_id, school_name, school_year, absence_count, is_chronically_absent)

Question: How many chronically absent students at Lincoln Elementary in 2023-2024?
SQL:"""

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=128, temperature=0.0)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

With llama.cpp (local-first path)

Use the matching GGUF:

llama-cli \
  -m lfed-qwen2.5-coder-14b-sql-gguf/ggml-model-q4_k_m.gguf \
  -p "Question: How many chronically absent students at Lincoln Elementary in 2023-2024?\nSQL:" \
  -n 128 --temp 0.0

Or run the full LFED app locally:

git checkout -b product local-llamacpp-v1
python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python app.py

---

Bias, Risks, and Limitations

• Synthetic data: the training data is generated from templates and rephrased. Demographic patterns in the seed data do not represent any real population; they exist to exercise joins and filters.
• No PII handling training: the model has no special safeguards around personally identifiable information because the schema uses anonymized student_ids only.
• Read-only enforcement is app-level: the adapter itself will emit any SQL-like text; the downstream data_engine.py validator enforces SELECT-only and forbidden-token rules.
• Hallucinated columns/tables: the model may occasionally reference a plausible-sounding column that does not exist. The execution guard catches these via schema-aware EXPLAIN validation.
• Numeric accuracy: the model writes the SQL; percentage interpretation depends on the application layer. Users should verify rates and percentages against their own conventions.

---

Environmental Impact

Estimated training energy use on a Modal A10G for ~2 epochs:

• Hardware type: NVIDIA A10G
• Training time: approximately 1–2 hours
• Cloud provider: Modal
• Region: likely US-east (Modal default)
• Carbon emitted: not precisely measured; rough estimate using ML CO2 Impact calculator is on the order of tens to low-hundreds of grams of CO2eq.

---

Citation

If you use this model, please cite the base model and the LFED project:

BibTeX:

@misc{lfed_sql_adapter,
  title={Local First Education Data Framework: A Qwen2.5-Coder-14B LoRA Adapter for School-Data Text-to-SQL},
  author={build-small-hackathon},
  year={2026},
  howpublished={\url{https://huggingface.co/build-small-hackathon/lfed-qwen2.5-coder-14b-sql-lora}}
}

APA: build-small-hackathon. (2026). Local First Education Data Framework: A Qwen2.5-Coder-14B LoRA adapter for school-data text-to-SQL. Hugging Face. https://huggingface.co/build-small-hackathon/lfed-qwen2.5-coder-14b-sql-lora

---

Framework versions

• PEFT 0.19.1