README.md

---
base_model: mlx-community/Qwen2.5-Coder-3B-Instruct-4bit
library_name: mlx
pipeline_tag: text-generation
language:
- en
tags:
- mlx
- mlx-lm
- lora
- adapter
- text-to-sql
- sqlite
license: other
datasets:
- b-mc2/sql-create-context
---

# Qwen2.5-Coder-3B Text-to-SQL LoRA Adapter for MLX

This is a LoRA adapter for `mlx-community/Qwen2.5-Coder-3B-Instruct-4bit`, trained locally with MLX-LM on Apple Silicon for schema-conditioned text-to-SQL generation.

## Results

On a frozen 1,000-example held-out set with context groups disjoint from the 5,000 training rows:

| Metric | Base model | This adapter |
| --- | ---: | ---: |
| Normalized reference-SQL exact match | 5.2% | **77.0%** |
| Parser-valid SQL | 99.0% | **99.6%** |
| SELECT-only SQL | 99.0% | **99.6%** |

Exact match is normalized agreement with the dataset reference SQL, **not** a semantic-equivalence or database-execution result. SQL validity is parser-only; no database is opened or executed.

## Base model and compatibility

- **Base:** `mlx-community/Qwen2.5-Coder-3B-Instruct-4bit`
- **Pinned base revision:** `3dd939c621c08e5753d5b89f35a2642cd83b98ca`
- **Runtime tested:** MLX 0.32.2 and MLX-LM 0.31.3
- **Adapter type:** MLX-LM LoRA, rank 16, final 16 transformer layers

This repository contains an adapter only. It requires the base model above and an MLX-LM-compatible Apple Silicon environment.

## Usage

```python
from mlx_lm import generate, load

base_model = "mlx-community/Qwen2.5-Coder-3B-Instruct-4bit"
# Replace this placeholder with the local directory containing the downloaded
# files from this Hugging Face repository.
adapter_path = "/path/to/qwen25-coder-3b-sql-create-context-lora-mlx"

model, tokenizer = load(base_model, adapter_path=adapter_path)
messages = [
    {
        "role": "system",
        "content": "You translate natural-language questions into SQLite SQL. Return exactly one read-only SELECT statement. Use only the supplied schema. Return SQL only: no Markdown fences, explanation, or comments.",
    },
    {
        "role": "user",
        "content": "Schema:\\nCREATE TABLE employees (id INTEGER, name TEXT);\\n\\nQuestion: List employee names.\\n\\nSQL:",
    },
]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
print(generate(model, tokenizer, prompt=prompt, max_tokens=256, verbose=False))
```

## Training data and method

- Dataset: `b-mc2/sql-create-context`, revision `9d80a6a118b838d9defc3798d659a54a2ac2ff37`
- Inputs: supplied `CREATE TABLE` schema context plus natural-language question
- Target: reference SQLite SQL answer
- Split: 5,000 training and 1,000 held-out rows grouped by identical full schema context; zero shared context groups
- Training: 2,500 micro-batches, batch size 2, gradient accumulation 4, learning rate `1e-5`, prompt loss masking

The complete, runnable training recipe—including project-relative data and
adapter paths—is [`configs/lora.yaml`](https://github.com/karyboy/mlx-text-to-sql-lora/blob/main/configs/lora.yaml).

## Limitations

- This is a local, schema-conditioned subset experiment, not a production SQL agent.
- Exact match can mark semantically equivalent SQL as incorrect.
- The evaluator does not execute queries, validate schema references, or assess result equivalence.
- Use generated SQL with normal application-level authorization and review controls.

## License and attribution

The training dataset is distributed under CC-BY-4.0 and should be attributed to `b-mc2/sql-create-context`. This adapter is derived from Qwen2.5-Coder-3B-Instruct; use is subject to the [Qwen Research License](https://huggingface.co/Qwen/Qwen2.5-Coder-3B-Instruct/blob/main/LICENSE). This model card does not grant rights beyond those upstream terms.

## Project source

The accompanying experiment code and technical report are published at [karyboy/mlx-text-to-sql-lora](https://github.com/karyboy/mlx-text-to-sql-lora).