docs: v2 model card - GGUF/Ollama/vLLM/TGI, benchmark table, collection link

README.md

@@ -1,22 +1,319 @@
 ---
-base_model: unsloth/Qwen2.5-Coder-7B-Instruct-bnb-4bit
-tags:
-- text-generation-inference
-- transformers
-- unsloth
-- qwen2
-- trl
 license: apache-2.0
+base_model: unsloth/Qwen2.5-Coder-7B-Instruct
+tags:
+  - code
+  - leetcode
+  - python
+  - code-generation
+  - competitive-programming
+  - qwen2.5-coder
+  - qlora
+  - unsloth
+  - algorithms
 language:
-- en
+  - en
+library_name: peft
+pipeline_tag: text-generation
+datasets:
+  - AmareshHebbar/leetcode-python-sft
+co2_eq_emissions:
+  emissions: 0
+  source: "estimate, not measured with a carbon-tracking tool"
+  training_type: "fine-tuning"
+  geographical_location: "EU-West"
+  hardware_used: "NVIDIA A40 (48GB)"
+model-index:
+  - name: leetcode-python-qwen25-coder-7b
+    results: []
+---
+
+<div align="center">
+
+# 🐍 LeetCode Python Coder
+### Qwen2.5-Coder-7B fine-tuned to solve LeetCode problems in Python
+
+[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Model-leetcode--python--qwen25--coder--7b-FFD21E)](https://huggingface.co/AmareshHebbar/leetcode-python-qwen25-coder-7b)
+[![Dataset](https://img.shields.io/badge/%F0%9F%A4%97%20Dataset-leetcode--python--sft-blue)](https://huggingface.co/datasets/AmareshHebbar/leetcode-python-sft)
+[![GGUF](https://img.shields.io/badge/GGUF-quantized-6f42c1)](https://huggingface.co/AmareshHebbar/leetcode-python-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)
+[![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*
+
+</div>
+
+---
+
+## TL;DR
+
+Given a LeetCode-style problem statement and an algorithm tag, generates a working Python 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.
+ALGORITHM: Hash Map
+OUTPUT (Python):
+def twoSum(nums, target):
+    seen = {}
+    for i, n in enumerate(nums):
+        if target - n in seen:
+            return [seen[target - n], i]
+        seen[n] = i
+```
+
+| | |
+|---|---|
+| **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-python-sft](https://huggingface.co/datasets/AmareshHebbar/leetcode-python-sft) |
+| **Weights here** | LoRA adapter only (~160MB) — load on top of the base model |
+| **GGUF build** | [leetcode-python-qwen25-coder-7b-GGUF](https://huggingface.co/AmareshHebbar/leetcode-python-qwen25-coder-7b-GGUF) — q4_k_m / q5_k_m / q8_0 |
+| **License** | Apache 2.0 |
+
+---
+
+## Benchmarks (free, reproducible)
+
+Run `benchmark_suite.py` from the deployment kit to reproduce. All numbers are pass@1 unless noted.
+
+| Benchmark | Language | Pass@1 | Pass@10 | Notes |
+|---|---|---|---|---|
+| [HumanEval-X](https://huggingface.co/datasets/THUDM/humaneval-x) | Python | _run benchmark_suite.py_ | _run benchmark_suite.py_ | 164 problems, execution-verified |
+| [MultiPL-E](https://huggingface.co/datasets/nuprl/MultiPL-E) (HumanEval subset) | Python | _run benchmark_suite.py_ | — | cross-check vs HumanEval-X |
+| Held-out LeetCode test split | Python | _run benchmark_suite.py_ | — | from `leetcode-python-sft` test split, exact I/O match |
+| Tokens/sec (fp16, A40) | Python | — | — | latency benchmark, see script |
+| Tokens/sec (GGUF q4_k_m, CPU) | Python | — | — | latency benchmark, see script |
+
+> Numbers are intentionally left blank in this template — `benchmark_suite.py` fills a `results/leetcode-python-qwen25-coder-7b.json` file and this table should be regenerated from it (see deployment kit README).
+
+---
+
+## Intended use
+
+Drop-in solution generator for Python coding-practice tools, interview-prep apps, and automated code-review sandboxes for algorithmic problems.
+
+### Direct use
+Give a problem statement (+ optional algorithm hint), get back a Python function/class implementing it.
+
+### Downstream use
+Feed output into an automated grader (run against test cases), a code-review bot, or a practice-app "show solution" feature.
+
+### Out of scope
+- Production system design or non-algorithmic code (this model specializes narrowly on LeetCode-style problems)
+- Security-critical code without human review
+- Guaranteed-optimal complexity — treat output as a strong first draft, not a proof
+
+---
+
+## Quickstart
+
+### Option A — Transformers + PEFT
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+import torch
+
+base_model = "unsloth/Qwen2.5-Coder-7B-Instruct"
+adapter    = "AmareshHebbar/leetcode-python-qwen25-coder-7b"
+
+tokenizer = AutoTokenizer.from_pretrained("AmareshHebbar/leetcode-python-qwen25-coder-7b")
+model = AutoModelForCausalLM.from_pretrained(
+    base_model,
+    torch_dtype=torch.bfloat16,
+    device_map="auto",
+)
+model = PeftModel.from_pretrained(model, adapter)
+
+messages = [
+    {"role": "system", "content": "You are an expert Python competitive programmer. Given a LeetCode-style problem statement and an algorithm tag, write a correct, efficient Python solution."},
+    {"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.2, do_sample=True)
+print(tokenizer.decode(outputs[0][inputs.shape[1]:], skip_special_tokens=True))
+```
+
+### Option B — Unsloth (2x faster load + inference)
+
+```python
+from unsloth import FastLanguageModel
+
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name="AmareshHebbar/leetcode-python-qwen25-coder-7b",
+    max_seq_length=2048,
+    load_in_4bit=True,
+)
+FastLanguageModel.for_inference(model)
+
+messages = [
+    {"role": "system", "content": "You are an expert Python competitive programmer. Given a LeetCode-style problem statement and an algorithm tag, write a correct, efficient Python solution."},
+    {"role": "user", "content": "Problem: Given a string s, find the length of the longest substring without repeating characters.\nAlgorithm: two pointers / sliding window"},
+]
+prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(prompt, return_tensors="pt").to("cuda")
+outputs = model.generate(**inputs, max_new_tokens=512, temperature=0.2, do_sample=True)
+print(tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))
+```
+
+### Option C — vLLM (production serving, OpenAI-compatible) {#vllm}
+
+```bash
+vllm serve unsloth/Qwen2.5-Coder-7B-Instruct \
+    --enable-lora \
+    --lora-modules leetcode-python-qwen25-coder-7b=AmareshHebbar/leetcode-python-qwen25-coder-7b \
+    --host 0.0.0.0 --port 8000 --dtype bfloat16
+```
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
+response = client.chat.completions.create(
+    model="leetcode-python-qwen25-coder-7b",
+    messages=[
+        {"role": "system", "content": "You are an expert Python competitive programmer. Given a LeetCode-style problem statement and an algorithm tag, write a correct, efficient Python solution."},
+        {"role": "user", "content": "Problem: Merge two sorted linked lists into one sorted list.\nAlgorithm: linked list, dummy head"},
+    ],
+    temperature=0.2,
+)
+print(response.choices[0].message.content)
+```
+
+### Option D — TGI (Text Generation Inference) {#tgi}
+
+```bash
+docker run --gpus all --shm-size 1g -p 8080:80 \
+    -v $PWD/data:/data ghcr.io/huggingface/text-generation-inference:latest \
+    --model-id unsloth/Qwen2.5-Coder-7B-Instruct \
+    --lora-adapters leetcode-python-qwen25-coder-7b=AmareshHebbar/leetcode-python-qwen25-coder-7b
+```
+
+```bash
+curl 127.0.0.1:8080/generate_stream \
+    -X POST \
+    -d '{"inputs":"<|im_start|>system\nYou are an expert Python competitive programmer. Given a LeetCode-style problem statement and an algorithm tag, write a correct, efficient Python solution.<|im_end|>\n<|im_start|>user\nProblem: 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<|im_end|>\n<|im_start|>assistant\n","parameters":{"max_new_tokens":512}}' \
+    -H 'Content-Type: application/json'
+```
+
+### Option E — Ollama (local, mobile/edge-friendly) {#ollama}
+
+```bash
+# 1. Pull the GGUF build
+huggingface-cli download AmareshHebbar/leetcode-python-qwen25-coder-7b-GGUF leetcode-python-qwen25-coder-7b.q4_k_m.gguf --local-dir .
+
+# 2. Create the model from the Modelfile shipped in the deployment kit (see deploy_ollama.py)
+ollama create leetcode-python-qwen25-coder-7b -f Modelfile.python
+
+# 3. Run it
+ollama run leetcode-python-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"
+```
+
+### Option F — GGUF / llama.cpp direct (mobile/edge inference)
+
+```bash
+./llama-cli -m leetcode-python-qwen25-coder-7b.q4_k_m.gguf \
+    -p "<|im_start|>system\nYou are an expert Python competitive programmer. Given a LeetCode-style problem statement and an algorithm tag, write a correct, efficient Python solution.<|im_end|>\n<|im_start|>user\nProblem: Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.<|im_end|>\n<|im_start|>assistant\n" \
+    -n 512 --temp 0.2
+```
+
+See `export_gguf.py` in the deployment kit for building q4_k_m / q5_k_m / q8_0 variants, and the mobile integration notes there for Android (llama.cpp JNI) and iOS (llama.cpp via Swift bindings).
+
+---
+
+## Training details
+
+### Data
+
+Trained on [leetcode-python-sft](https://huggingface.co/datasets/AmareshHebbar/leetcode-python-sft), built from the `doocs/leetcode` corpus: problem statement + input/output examples + algorithm tag → verified Python solution, one-to-many (problem → multiple algorithm-tagged solutions).
+
+### Hyperparameters
+
+| Parameter | Value |
+|---|---|
+| 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) |
+| Max sequence length | 2048 |
+| Optimizer | paged_adamw_8bit |
+| LR schedule | 2e-4, cosine |
+
+### Training compute
+
+| | |
+|---|---|
+| **GPU** | NVIDIA A40 (48GB) |
+| **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`.
+
+---
+
+## Bias, risks & limitations
+
+**Narrow specialization.** This model is tuned tightly on LeetCode-style algorithmic problems — general software-engineering code (frameworks, infra, business logic) is out of distribution.
+
+**Verify before trusting.** Like any LLM, generated solutions can look plausible and still fail an edge case (empty input, integer overflow, off-by-one). Always run against test cases before use.
+
+**Not exhaustive on complexity.** The model doesn't guarantee asymptotically optimal solutions — check the complexity claims yourself for performance-sensitive use.
+
+---
+
+## 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()`.
+
+**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: 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.
+
+---
+
+## Related models in this suite
+
+| Model | Language |
+|---|---|
+| [leetcode-python-qwen25-coder-7b](https://huggingface.co/AmareshHebbar/leetcode-python-qwen25-coder-7b) | Python (this model) |
+| [leetcode-java-qwen25-coder-7b](https://huggingface.co/AmareshHebbar/leetcode-java-qwen25-coder-7b) | Java |
+| [leetcode-cpp-qwen25-coder-7b](https://huggingface.co/AmareshHebbar/leetcode-cpp-qwen25-coder-7b) | C++ |
+| [leetcode-javascript-qwen25-coder-7b](https://huggingface.co/AmareshHebbar/leetcode-javascript-qwen25-coder-7b) | JavaScript |
+
+**Full collection:** [LeetCode Multi-Language Coder Suite](https://huggingface.co/collections/AmareshHebbar/leetcode-multi-language-coder-suite)
+
+---
+
+## Changelog
+
+| Version | Notes |
+|---|---|
+| 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-python-sft |
+
 ---
 
-# Uploaded  model
+## Citation
 
-- **Developed by:** AmareshHebbar
-- **License:** apache-2.0
-- **Finetuned from model :** unsloth/Qwen2.5-Coder-7B-Instruct-bnb-4bit
+```bibtex
+@misc{leetcodecoder2026,
+  author    = {Hebbar, Amaresh},
+  title     = {LeetCode Multi-Language Coder Suite},
+  year      = {2026},
+  publisher = {HuggingFace},
+  url       = {https://huggingface.co/AmareshHebbar}
+}
+```
 
-This qwen2 model was trained 2x faster with [Unsloth](https://github.com/unslothai/unsloth) and Huggingface's TRL library.
+## Contact
 
-[<img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" width="200"/>](https://github.com/unslothai/unsloth)
+[![GitHub](https://img.shields.io/badge/GitHub-amareshhebbar-181717?logo=github)](https://github.com/amareshhebbar)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-gvamaresh-0A66C2?logo=linkedin)](https://www.linkedin.com/in/gvamaresh)
+[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Profile-AmareshHebbar-FFD21E)](https://huggingface.co/AmareshHebbar)