neuralbroker
/

blitzkode-1.5b-lora

@@ -1,183 +1,84 @@
----
-language:
-  - en
-license: mit
-library_name: peft
-tags:
-  - code-generation
-  - lora
-  - qwen2.5
-  - blitzkode
-  - coding-assistant
-  - fine-tuned
-  - peft
-base_model: Qwen/Qwen2.5-1.5B-Instruct
-pipeline_tag: text-generation
----
-# BlitzKode LoRA Adapter (0.5B)
-**BlitzKode** is a local AI coding assistant fine-tuned from
-**[Qwen/Qwen2.5-1.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct)** using LoRA
-(Low-Rank Adaptation). This repository contains the PEFT adapter — the
-research-friendly version that can be hot-loaded on top of the base model.
-> **Creator:** [Sajad (neuralbroker)](https://github.com/neuralbroker)
-> **GitHub:** <https://github.com/neuralbroker/blitzkode>
-> **Production GGUF:** [`neuralbroker/blitzkode`](https://huggingface.co/neuralbroker/blitzkode)
----
-## Model Details
-| Property | Value |
-|---|---|
-| **Adapter version** | 2.1 |
-| **Base model** | `Qwen/Qwen2.5-1.5B-Instruct` |
-| **LoRA rank (r)** | 16 |
-| **LoRA alpha** | 32 |
-| **LoRA dropout** | 0.05 |
-| **Target modules** | `up_proj`, `down_proj`, `q_proj`, `o_proj`, `k_proj`, `gate_proj`, `v_proj` |
-| **Training steps** | 50 |
-| **Final loss** | ~0.48 |
-| **Library** | PEFT |
-| **License** | MIT |
----
-## Training Pipeline
-This adapter was produced by a **4-stage fine-tuning pipeline** applied
-to the Qwen2.5 family:
-| Stage | Method | Purpose |
-|---|---|---|
-| 1 | SFT | Supervised fine-tuning on 71 curated algorithmic coding problems |
-| 2 | Reward-SFT | Continued SFT with heuristic reward signals for code correctness and formatting |
-| 3 | DPO | Direct Preference Optimization on handcrafted chosen/rejected pairs |
-| 4 | LoRA SFT (this adapter) | Final LoRA fine-tune (r=16) on 99 samples; base model Qwen2.5-0.5B |
-### Training Dataset (199 total samples)
-| Subset | Count | Source | License |
-|---|---|---|---|
-| Curated algorithmic problems | 71 | Custom (local) — arrays, strings, trees, DP, graphs | MIT |
-| MetaMathQA samples | 100 | [`meta-math/MetaMathQA`](https://huggingface.co/datasets/meta-math/MetaMathQA) | CC BY 4.0 |
-| Python/JavaScript patterns | 28 | Custom (local) — decorators, context managers, data classes | MIT |
-| **Total** | **199** | | |
----
-## Usage
-### Load with PEFT
-```python
-from peft import PeftModel
-from transformers import AutoModelForCausalLM, AutoTokenizer
-base_model_id = "Qwen/Qwen2.5-1.5B-Instruct"
-adapter_repo  = "neuralbroker/blitzkode-1.5b-lora"
-tokenizer = AutoTokenizer.from_pretrained(base_model_id, trust_remote_code=True)
-model = AutoModelForCausalLM.from_pretrained(
-    base_model_id,
-    torch_dtype="auto",
-    device_map="auto",
-    trust_remote_code=True,
-)
-model = PeftModel.from_pretrained(model, adapter_repo)
-model.eval()
-```
-### Generate code
-```python
-prompt = (
-    "<|im_start|>system\n"
-    "You are BlitzKode, a precise AI coding assistant created by Sajad.\n"
-    "<|im_end|>\n"
-    "<|im_start|>user\n"
-    "Write a Python function for binary search with full edge-case handling.\n"
-    "<|im_end|>\n"
-    "<|im_start|>assistant\n"
-)
-inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
-outputs = model.generate(
-    **inputs,
-    max_new_tokens=300,
-    temperature=0.7,
-    do_sample=True,
-    repetition_penalty=1.1,
-)
-print(tokenizer.decode(outputs[0], skip_special_tokens=True))
-```
-### Merge adapter into base model (for export)
-```python
-merged = model.merge_and_unload()
-merged.save_pretrained("blitzkode-0.5b-merged")
-tokenizer.save_pretrained("blitzkode-0.5b-merged")
-```
----
-## Prompt Format
-BlitzKode uses the **ChatML** template standard for Qwen models:
-```
-<|im_start|>system
-You are BlitzKode, a precise AI coding assistant created by Sajad.<|im_end|>
-<|im_start|>user
-{your question}<|im_end|>
-<|im_start|>assistant
-```
----
-## Limitations
-- **Text-only** — no image/multimodal support.
-- **0.5B parameters** — smaller and faster than the 1.5B GGUF variant; may be
-  less accurate on complex algorithmic tasks.
-- **2048-token context** — not suitable for long repository-level analysis.
-- **Review all outputs** — generated code must be tested before use in production.
-- **Not security-audited** — do not use for cryptographic or safety-critical code
-  without thorough expert review.
-- **Math reasoning** — MetaMathQA training improves basic reasoning but does not
-  substitute a dedicated math model.
----
-## Relation to the Production Model
-| Variant | Repo | Size | Runtime | Use case |
-|---|---|---|---|---|
-| GGUF (1.5B, F16) | [`neuralbroker/blitzkode`](https://huggingface.co/neuralbroker/blitzkode) | ~3 GB | llama.cpp / llama-cpp-python | Production; CPU/GPU, no Python ML stack needed |
-| LoRA adapter (0.5B) | `neuralbroker/blitzkode-1.5b-lora` (this repo) | ~100 MB | PEFT + Transformers | Research; merging, further fine-tuning, quantization |
----
-## License
-**MIT** — see [LICENSE](https://github.com/neuralbroker/blitzkode/blob/main/LICENSE).
-You must also comply with the upstream
-[Qwen/Qwen2.5-1.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct) license
-when redistributing any derived weights.
----
-## Citation
-```bibtex
-@software{blitzkode2025,
-  author  = {Sajad},
-  title   = {BlitzKode: A Local AI Coding Assistant},
-  year    = {2025},
-  url     = {https://github.com/neuralbroker/blitzkode}
-}
-```

+---
+language:
+  - en
+license: mit
+library_name: peft
+pipeline_tag: text-generation
+tags:
+  - code-generation
+  - coding-assistant
+  - lora
+  - peft
+  - qwen2.5
+  - blitzkode
+base_model: Qwen/Qwen2.5-1.5B-Instruct
+---
+# BlitzKode 1.5B LoRA Adapter
+This repository contains the **BlitzKode 1.5B PEFT/LoRA adapter** for `Qwen/Qwen2.5-1.5B-Instruct`. It is intended for research, inspection, and reproducible adapter loading. The production local-inference artifact is the merged GGUF model at [`neuralbroker/blitzkode`](https://huggingface.co/neuralbroker/blitzkode).
+## Intended use
+- Local coding-assistant research
+- Adapter inspection and continued fine-tuning
+- Reproducing the BlitzKode GGUF export pipeline
+- Educational experiments with PEFT/LoRA on Qwen2.5
+Do **not** use generated code in production without review and tests.
+## Loading
+```python
+from peft import PeftModel
+from transformers import AutoModelForCausalLM, AutoTokenizer
+base_model_id = "Qwen/Qwen2.5-1.5B-Instruct"
+adapter_id = "neuralbroker/blitzkode-1.5b-lora"
+tokenizer = AutoTokenizer.from_pretrained(base_model_id, trust_remote_code=True)
+model = AutoModelForCausalLM.from_pretrained(
+    base_model_id,
+    torch_dtype="auto",
+    device_map="auto",
+    trust_remote_code=True,
+)
+model = PeftModel.from_pretrained(model, adapter_id)
+model.eval()
+```
+## Training summary
+BlitzKode was developed through staged coding-assistant post-training:
+| Stage | Method | Purpose |
+|---|---|---|
+| SFT | Curated coding examples | Teach concise coding responses and common algorithms |
+| Reward-SFT | Heuristic continuation | Reinforce formatting, correctness patterns, and practical explanations |
+| DPO | Preference pairs | Penalize weak answers and hallucinated details |
+| Export | Merge + GGUF | Produce the production `blitzkode.gguf` artifact |
+Dataset provenance is tracked in the GitHub project and the production model repository docs.
+## Evaluation
+The latest published smoke evaluation is attached to the production GGUF repository: [`neuralbroker/blitzkode`](https://huggingface.co/neuralbroker/blitzkode). Current GGUF smoke eval: **3 / 4 passed (75%)** on Python factorial, binary search, SQL top users, and fictional-API uncertainty checks. The raw model still fails the fictional-API uncertainty case, so downstream serving should keep guardrails enabled.
+This is a lightweight regression smoke eval, not a comprehensive benchmark such as HumanEval, MBPP, or SWE-bench.
+## Limitations
+- Small-model limitations apply; outputs can be wrong or incomplete.
+- Direct prompting may hallucinate unsupported APIs or signatures.
+- Default deployment context is 2,048 tokens.
+- Text-only model; no image/file multimodal support.
+## Related repositories
+- Production GGUF/API docs: [`neuralbroker/blitzkode`](https://huggingface.co/neuralbroker/blitzkode)
+- Lightweight 0.5B adapter: [`neuralbroker/blitzkode-lora-0.5b`](https://huggingface.co/neuralbroker/blitzkode-lora-0.5b)
+- GitHub source: <https://github.com/neuralbroker/blitzkode>
+## License
+MIT for BlitzKode project files and adapter release metadata. You must also comply with the upstream Qwen2.5 license for the base model.