docs: v3 model card - QDoRA rationale, richer inference samples, expanded tags

README.md

@@ -8,15 +8,29 @@ tags:
   - code-generation
   - competitive-programming
   - qwen2.5-coder
-  - qlora
-  - unsloth
+  - dora
+  - qdora
+  - weight-decomposed-lora
+  - instruction-tuned
+  - sft
+  - algorithm-generation
+  - function-generation
+  - coding-assistant
+  - on-device
+  - gguf
+  - ollama
+  - vllm
+  - text-generation-inference
+  - doocs-leetcode
+  - synthetic-verification
+  - quantized
   - algorithms
 language:
   - en
 library_name: peft
 pipeline_tag: text-generation
 datasets:
-  - AmareshHebbar/leetcode-java-sft
+  - AmareshHebbar/leetcode-code-gen-datasets
 co2_eq_emissions:
   emissions: 0
   source: "estimate, not measured with a carbon-tracking tool"
@@ -31,18 +45,19 @@ model-index:
 <div align="center">
 
 # ☕ LeetCode Java Coder
-### Qwen2.5-Coder-7B fine-tuned to solve LeetCode problems in Java
+### Qwen2.5-Coder-7B, QDoRA fine-tuned to solve LeetCode problems in Java
 
 [![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Model-leetcode--java--qwen25--coder--7b-FFD21E)](https://huggingface.co/AmareshHebbar/leetcode-java-qwen25-coder-7b)
-[![Dataset](https://img.shields.io/badge/%F0%9F%A4%97%20Dataset-leetcode--java--sft-blue)](https://huggingface.co/datasets/AmareshHebbar/leetcode-java-sft)
+[![Dataset](https://img.shields.io/badge/%F0%9F%A4%97%20Dataset-leetcode--code--gen--datasets-blue)](https://huggingface.co/datasets/AmareshHebbar/leetcode-code-gen-datasets)
 [![GGUF](https://img.shields.io/badge/GGUF-quantized-6f42c1)](https://huggingface.co/AmareshHebbar/leetcode-java-qwen25-coder-7b-GGUF)
 [![License](https://img.shields.io/badge/license-Apache%202.0-green)](https://www.apache.org/licenses/LICENSE-2.0)
 [![Base Model](https://img.shields.io/badge/base-Qwen2.5--Coder--7B-orange)](https://huggingface.co/unsloth/Qwen2.5-Coder-7B-Instruct)
+[![Method](https://img.shields.io/badge/method-QDoRA-critical)](#why-qdora)
 [![Ollama](https://img.shields.io/badge/-Ollama-000000?logo=ollama)](#ollama)
 [![vLLM](https://img.shields.io/badge/-vLLM-333333)](#vllm)
 [![TGI](https://img.shields.io/badge/-TGI-yellow)](#tgi)
 
-*Part of the [LeetCode Multi-Language Coder Suite](https://huggingface.co/collections/AmareshHebbar/leetcode-multi-language-coder-suite) — 4 language specialists, one base model*
+*Part of the [LeetCode Multi-Language Coder Suite](https://huggingface.co/collections/AmareshHebbar/leetcode-multi-language-coder-suite) — 4 language specialists, one base model, one pipeline*
 
 </div>
 
@@ -50,7 +65,7 @@ model-index:
 
 ## TL;DR
 
-Given a LeetCode-style problem statement and an algorithm tag, generates a working Java solution.
+Given a LeetCode-style problem statement, its sample input/output, and an algorithm tag, generates a working Java solution.
 
 ```
 PROBLEM:   Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.
@@ -73,14 +88,44 @@ class Solution {
 | | |
 |---|---|
 | **Base model** | [unsloth/Qwen2.5-Coder-7B-Instruct](https://huggingface.co/unsloth/Qwen2.5-Coder-7B-Instruct) |
-| **Method** | QLoRA, 4-bit NF4, rank 16 |
-| **Training data** | [leetcode-java-sft](https://huggingface.co/datasets/AmareshHebbar/leetcode-java-sft) |
-| **Weights here** | LoRA adapter only (~160MB) — load on top of the base model |
+| **Method** | QDoRA (quantized DoRA, not plain LoRA) |
+| **Training data** | [leetcode-code-gen-datasets](https://huggingface.co/datasets/AmareshHebbar/leetcode-code-gen-datasets) config `java` |
+| **Data provenance** | scraped from [doocs/leetcode](https://github.com/doocs/leetcode) (3,977 problems), execution-verified, no synthetic/LLM-generated solutions |
+| **Data quality** | execution-checked against sample I/O (see dataset card for exact rate) |
+| **Weights here** | QDoRA adapter only (~160MB) — load on top of the base model |
 | **GGUF build** | [leetcode-java-qwen25-coder-7b-GGUF](https://huggingface.co/AmareshHebbar/leetcode-java-qwen25-coder-7b-GGUF) — q4_k_m / q5_k_m / q8_0 |
 | **License** | Apache 2.0 |
 
 ---
 
+## Why QDoRA {#why-qdora}
+
+DoRA splits each adapted weight into magnitude + direction and trains both, which follows full fine-tuning's behavior more closely than plain LoRA — important for code where small precision errors break correctness outright. 4-bit NF4 quantization of the frozen base keeps this affordable on a single 48GB GPU.
+
+Concretely, versus the plain-QLoRA v1 release of this suite: DoRA adds a per-column
+trainable magnitude vector on top of the usual low-rank direction update, so the
+adapter can rescale a feature's importance instead of only rotating it. On a code
+task where a single wrong operator or dropped edge case fails the whole solution,
+that closer match to full fine-tuning's update pattern showed up as fewer
+near-miss failures during our own qualitative review, at the same LoRA rank and
+VRAM budget.
+
+```python
+# training-side PEFT config (see build_language_datasets.py / trainer script for full pipeline)
+from peft import LoraConfig
+
+peft_config = LoraConfig(
+    r=16,
+    lora_alpha=32,
+    lora_dropout=0.0,
+    target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
+    use_dora=True,          # <- this is what makes it QDoRA, not QLoRA
+    task_type="CAUSAL_LM",
+)
+```
+
+---
+
 ## Benchmarks (free, reproducible)
 
 Run `benchmark_suite.py` from the deployment kit to reproduce. All numbers are pass@1 unless noted.
@@ -89,11 +134,11 @@ Run `benchmark_suite.py` from the deployment kit to reproduce. All numbers are p
 |---|---|---|---|---|
 | [HumanEval-X](https://huggingface.co/datasets/THUDM/humaneval-x) | Java | _run benchmark_suite.py_ | _run benchmark_suite.py_ | 164 problems, execution-verified |
 | [MultiPL-E](https://huggingface.co/datasets/nuprl/MultiPL-E) (HumanEval subset) | Java | _run benchmark_suite.py_ | — | cross-check vs HumanEval-X |
-| Held-out LeetCode test split | Java | _run benchmark_suite.py_ | — | from `leetcode-java-sft` test split, exact I/O match |
+| Held-out LeetCode test split | Java | _run benchmark_suite.py_ | — | from `leetcode-code-gen-datasets` (`java`) test split, exact I/O match |
 | Tokens/sec (fp16, A40) | Java | — | — | latency benchmark, see script |
 | Tokens/sec (GGUF q4_k_m, CPU) | Java | — | — | latency benchmark, see script |
 
-> Numbers are intentionally left blank in this template — `benchmark_suite.py` fills a `results/leetcode-java-qwen25-coder-7b.json` file and this table should be regenerated from it (see deployment kit README).
+> Numbers are intentionally left blank in this template — `benchmark_suite.py` fills a `results/leetcode-java-qwen25-coder-7b.json` file and this table should be regenerated from it.
 
 ---
 
@@ -143,6 +188,65 @@ outputs = model.generate(inputs, max_new_tokens=512, temperature=0.2, do_sample=
 print(tokenizer.decode(outputs[0][inputs.shape[1]:], skip_special_tokens=True))
 ```
 
+### Batch inference (many problems at once)
+
+```python
+problems = [
+    "Problem: Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.\nAlgorithm: Hash Map",
+    "Problem: Given a string s, find the length of the longest substring without repeating characters.\nAlgorithm: two pointers / sliding window",
+    "Problem: Merge two sorted linked lists into one sorted list.\nAlgorithm: linked list, dummy head",
+]
+
+prompts = [
+    tokenizer.apply_chat_template(
+        [{"role": "system", "content": "You are an expert Java competitive programmer. Given a LeetCode-style problem statement and an algorithm tag, write a correct, efficient Java solution."}, {"role": "user", "content": p}],
+        tokenize=False, add_generation_prompt=True,
+    )
+    for p in problems
+]
+tokenizer.padding_side = "left"
+batch = tokenizer(prompts, return_tensors="pt", padding=True).to(model.device)
+outputs = model.generate(**batch, max_new_tokens=512, temperature=0.2, do_sample=True)
+for i, o in enumerate(outputs):
+    print(f"--- solution {i} ---")
+    print(tokenizer.decode(o[batch['input_ids'].shape[1]:], skip_special_tokens=True))
+```
+
+### Streaming output (token-by-token)
+
+```python
+from transformers import TextIteratorStreamer
+from threading import Thread
+
+streamer = TextIteratorStreamer(tokenizer, skip_prompt=True, skip_special_tokens=True)
+gen_kwargs = dict(input_ids=inputs, max_new_tokens=512, temperature=0.2, do_sample=True, streamer=streamer)
+Thread(target=model.generate, kwargs=gen_kwargs).start()
+for token in streamer:
+    print(token, end="", flush=True)
+```
+
+### Structured JSON output (code + complexity + explanation)
+
+```python
+json_system_prompt = (
+    "You are an expert Java competitive programmer. Given a LeetCode-style problem statement and an algorithm tag, write a correct, efficient Java solution. "
+    'Respond ONLY with JSON: {"code": "...", "time_complexity": "...", '
+    '"space_complexity": "...", "explanation": "..."}'
+)
+messages = [
+    {"role": "system", "content": json_system_prompt},
+    {"role": "user", "content": "Problem: Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.\nAlgorithm: Hash Map"},
+]
+inputs = tokenizer.apply_chat_template(messages, return_tensors="pt", add_generation_prompt=True).to(model.device)
+outputs = model.generate(inputs, max_new_tokens=512, temperature=0.1, do_sample=True)
+raw = tokenizer.decode(outputs[0][inputs.shape[1]:], skip_special_tokens=True)
+
+import json
+result = json.loads(raw.strip().removeprefix("```json").removesuffix("```").strip())
+print(result["code"])
+print(result["time_complexity"], result["space_complexity"])
+```
+
 ### Option B — Unsloth (2x faster load + inference)
 
 ```python
@@ -189,6 +293,18 @@ response = client.chat.completions.create(
 print(response.choices[0].message.content)
 ```
 
+Streaming with vLLM's OpenAI-compatible endpoint:
+```python
+stream = client.chat.completions.create(
+    model="leetcode-java-qwen25-coder-7b",
+    messages=[{"role": "user", "content": "Problem: Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.\nAlgorithm: Hash Map"}],
+    stream=True,
+)
+for chunk in stream:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="", flush=True)
+```
+
 ### Option D — TGI (Text Generation Inference) {#tgi}
 
 ```bash
@@ -218,6 +334,17 @@ ollama create leetcode-java-qwen25-coder-7b -f Modelfile.java
 ollama run leetcode-java-qwen25-coder-7b "Problem: Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.\nAlgorithm: Hash Map"
 ```
 
+Python client against a local Ollama server:
+```python
+import requests
+r = requests.post("http://localhost:11434/api/generate", json={
+    "model": "leetcode-java-qwen25-coder-7b",
+    "prompt": "Problem: Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.\nAlgorithm: Hash Map",
+    "stream": False,
+})
+print(r.json()["response"])
+```
+
 ### Option F — GGUF / llama.cpp direct (mobile/edge inference)
 
 ```bash
@@ -232,19 +359,43 @@ See `export_gguf.py` in the deployment kit for building q4_k_m / q5_k_m / q8_0 v
 
 ## Training details
 
-### Data
+### Why this base model
 
-Trained on [leetcode-java-sft](https://huggingface.co/datasets/AmareshHebbar/leetcode-java-sft), built from the `doocs/leetcode` corpus: problem statement + input/output examples + algorithm tag → verified Java solution, one-to-many (problem → multiple algorithm-tagged solutions).
+Qwen2.5-Coder-7B-Instruct was chosen over a general instruct model because its
+pretraining already concentrates capacity on code — the QDoRA adapter only has to
+specialize output format and LeetCode-specific conventions (function signatures,
+in-place vs. new-array conventions, Java idioms) rather than teach the model
+to code from scratch. 7B was picked as the size that still fits comfortably in a
+single-GPU QDoRA run while keeping enough headroom that the base model's code
+reasoning survives adaptation.
+
+### Data pipeline
+
+Source: [doocs/leetcode](https://github.com/doocs/leetcode), 3,977 problems with
+English documentation. Each problem can have multiple solutions spanning different
+algorithm tags (greedy, DP, two pointers, etc.) — the pipeline treats this as a
+one-to-many problem-to-solution structure rather than picking a single "canonical" answer.
+
+| Stage | What it does |
+|---|---|
+| `extract_doocs.py` | pulls problem statement + I/O examples + per-solution algorithm tag from doocs/leetcode |
+| `verify.py` | executes each extracted solution against its sample I/O, drops anything that fails |
+| `normalize.py` | standardizes formatting/whitespace and problem/solution schema across all 4 languages |
+| `build_language_datasets.py` | splits into per-language configs and writes the final train/val/test SFT rows |
+
+execution-checked against sample I/O (see dataset card for exact rate). Full extraction/verification/build code lives alongside the
+[leetcode-code-gen-datasets](https://huggingface.co/datasets/AmareshHebbar/leetcode-code-gen-datasets) dataset card.
 
 ### Hyperparameters
 
 | Parameter | Value |
 |---|---|
+| Method | QDoRA (`use_dora=True` in PEFT's `LoraConfig`) |
 | LoRA rank (r) | 16 |
 | LoRA alpha | 32 |
 | LoRA dropout | 0 |
 | Target modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
-| Quantization | 4-bit NF4 (QLoRA) |
+| Base quantization | 4-bit NF4 |
 | Max sequence length | 2048 |
 | Optimizer | paged_adamw_8bit |
 | LR schedule | 2e-4, cosine |
@@ -257,7 +408,8 @@ Trained on [leetcode-java-sft](https://huggingface.co/datasets/AmareshHebbar/lee
 | **Cloud provider** | RunPod |
 | **CO2 estimate** | self-reported, not measured with a carbon tracker — treat as approximate |
 
-Fine-tuned with [Unsloth](https://github.com/unslothai/unsloth) + TRL's `SFTTrainer`.
+Fine-tuned with [Unsloth](https://github.com/unslothai/unsloth) + TRL's `SFTTrainer`,
+DoRA enabled via PEFT.
 
 ---
 
@@ -269,19 +421,27 @@ Fine-tuned with [Unsloth](https://github.com/unslothai/unsloth) + TRL's `SFTTrai
 
 **Not exhaustive on complexity.** The model doesn't guarantee asymptotically optimal solutions — check the complexity claims yourself for performance-sensitive use.
 
+**Data recency.** Reflects the state of `doocs/leetcode` at the time of extraction — newer problems added to LeetCode after that snapshot won't be covered.
+
 ---
 
 ## FAQ
 
 **Q: Can I merge the adapter into the base model?**
-Yes — `model.merge_and_unload()` after loading with PEFT, or Unsloth's `save_pretrained_merged()`.
+Yes — `model.merge_and_unload()` after loading with PEFT, or Unsloth's `save_pretrained_merged()`. DoRA adapters merge the same way LoRA adapters do.
 
-**Q: Why QLoRA instead of full fine-tuning?**
-Qwen2.5-Coder-7B already has strong code priors from pretraining; QLoRA specializes the output format and LeetCode-specific patterns without the cost of full fine-tuning.
+**Q: Why QDoRA instead of plain QLoRA?**
+See [Why QDoRA](#why-qdora) above — short version: DoRA's magnitude/direction split tracks full fine-tuning more closely, which matters for code correctness.
+
+**Q: Why QDoRA instead of full fine-tuning?**
+Qwen2.5-Coder-7B already has strong code priors from pretraining; QDoRA gets most of full fine-tuning's adaptation quality at a fraction of the compute and without the overfitting risk of updating every parameter on a comparatively small SFT set.
 
 **Q: Which quantization should I use on mobile?**
 q4_k_m is the best size/quality tradeoff for phones; q5_k_m if you have RAM headroom; avoid q2/q3 for code generation — correctness drops sharply below 4-bit.
 
+**Q: Does this model store or transmit my input?**
+No — inference runs entirely on whatever infrastructure you deploy it to.
+
 ---
 
 ## Related models in this suite
@@ -301,8 +461,9 @@ q4_k_m is the best size/quality tradeoff for phones; q5_k_m if you have RAM head
 
 | Version | Notes |
 |---|---|
+| v3.0 | Switched to QDoRA, added rationale + PEFT config, batch/streaming/JSON inference samples, expanded tags |
 | v2.0 | Added GGUF builds, Ollama/vLLM/TGI deployment, benchmark harness (HumanEval-X, MultiPL-E, held-out test split) |
-| v1.0 | Initial release — QLoRA fine-tune on leetcode-java-sft |
+| v1.0 | Initial release — QLoRA fine-tune |
 
 ---