Add model card

README.md

@@ -0,0 +1,87 @@
+---
+base_model: Qwen/Qwen2.5-Coder-7B-Instruct
+library_name: peft
+license: apache-2.0
+pipeline_tag: text-generation
+language: [en]
+datasets: [samrat-kar/ap-sql-peft]
+tags:
+- base_model:adapter:Qwen/Qwen2.5-Coder-7B-Instruct
+- lora
+- qlora
+- text-to-sql
+- oracle
+- accounts-payable
+---
+
+# ap-sql-v1
+
+A LoRA adapter for `Qwen/Qwen2.5-Coder-7B-Instruct` that turns Accounts Payable questions into read-only Oracle SQL.
+It is built for an AI data-analyst assistant that answers questions over a schema modelled on Oracle Fusion AP,
+Payments and Supplier tables.
+
+The model gets a system prompt containing the relevant table DDL (from schema retrieval) and a business glossary.
+It answers with a single ```` ```sql ```` block. It has also learned to fix a query when it is given the Oracle error
+from its previous attempt, and to answer follow-up questions in a conversation.
+
+## Results
+
+Execution accuracy on the 179-case held-out test split. The generated SQL and the gold SQL were both run on Oracle 23ai
+and their result sets compared. A case counts only when the rows match exactly. The adapter was served by
+vLLM 0.12.0 on the AWQ base `Qwen/Qwen2.5-Coder-7B-Instruct-AWQ`.
+
+| Model | T1 | T2 | T3 | T4 | T5 | Overall |
+|---|---|---|---|---|---|---|
+| Base `Qwen2.5-Coder-7B-Instruct-AWQ` | 57% | 32% | 21% | 32% | 56% | 35% |
+| **ap-sql-v1** | **97%** | **96%** | **90%** | **89%** | **89%** | **93%** |
+
+Invented-column errors (ORA-00904) fell from 43 cases to 0. The adapter adds about 1 second of median latency
+(2.8 s to 3.8 s on an RTX 5070 Ti Laptop GPU).
+
+**Caveats.** 149 of the 179 test cases are templated, as is most of the training set. No test case shares a template
+group or an identical question with the training data, but real user questions will vary more than the test set.
+The eval uses each case's stored prompt, so it measures the model on its own; schema retrieval is outside its scope.
+
+## Usage
+
+### vLLM
+
+```bash
+vllm serve Qwen/Qwen2.5-Coder-7B-Instruct-AWQ --quantization awq_marlin \
+  --enable-lora --max-lora-rank 16 --lora-modules ap-sql-v1=samrat-kar/ap-sql-v1
+```
+
+Then send `model="ap-sql-v1"` to the OpenAI-compatible `/v1/chat/completions` endpoint.
+
+### Transformers + PEFT
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-Coder-7B-Instruct", torch_dtype="auto", device_map="auto")
+model = PeftModel.from_pretrained(base, "samrat-kar/ap-sql-v1")
+tok = AutoTokenizer.from_pretrained("samrat-kar/ap-sql-v1")
+```
+
+Use the same system-prompt format as the training data (see the dataset). The schema must be given as `CREATE TABLE` DDL.
+
+## Training
+
+| | |
+|---|---|
+| Method | QLoRA: 4-bit NF4 base with double quantisation, bf16 compute |
+| LoRA | r=16, alpha=32, dropout=0.05; q/k/v/o/gate/up/down projections |
+| Data | 1,441 train / 95 val rows from `samrat-kar/ap-sql-peft` |
+| Schedule | 3 epochs, 273 optimizer steps, lr 2e-4 cosine, effective batch 16, paged AdamW 8-bit |
+| Max length | 3,840 tokens |
+| Final train loss | 0.0157 |
+| Compute | 2.5 h, peak 17.5 GB GPU memory |
+
+The loss is computed on the assistant turn only.
+
+## Limitations
+
+- Trained on a single demo schema. Other schemas, or other Fusion modules, need new training data.
+- Produces Oracle dialect only (`FETCH FIRST N ROWS ONLY`, `ADD_MONTHS`, `TRUNC`).
+- Always run the output through read-only guardrails and a read-only database user. The model is not a security boundary.