docs: improve model card with usage, benchmark table, limitations, citation

README.md

@@ -67,3 +67,141 @@ model-index:
       value: 71.2
       verified: false
 ---
+
+<p align="center">
+  <strong>SakThai Coder 1.5B — code + tool calling for CPU</strong><br/>
+  <em>Part of the <a href="https://huggingface.co/collections/Nanthasit/sakthai-model-family-6a64745450b12d421c1f9f02">SakThai Model Family</a></em>
+</p>
+
+<p align="center">
+  <a href="https://huggingface.co/Nanthasit"><img src="https://img.shields.io/badge/%F0%9F%A4%97-Nanthasit-6644cc" alt="Profile"/></a>
+  <a href="https://huggingface.co/collections/Nanthasit/sakthai-model-family-6a64745450b12d421c1f9f02"><img src="https://img.shields.io/badge/%F0%9F%8F%A0-SakThai%20Family-6644cc" alt="Collection"/></a>
+  <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fhuggingface.co%2Fapi%2Fmodels%2FNanthasit%2Fsakthai-coder-1.5b&query=%24.downloads&label=downloads&color=blue&cacheSeconds=3600" alt="Downloads"/>
+  <img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License"/>
+  <img src="https://img.shields.io/badge/base-Qwen2.5--Coder--1.5B--Instruct-orange" alt="Base model"/>
+  <img src="https://img.shields.io/badge/format-GGUF%20Q4_K_M-blueviolet" alt="Format"/>
+  <img src="https://img.shields.io/badge/inference-cpu--first-green" alt="CPU-first"/>
+</p>
+
+> This is the **coder branch** of the SakThai family: small, offline-capable, and tuned to write code while still supporting tool-style outputs. It is packaged as a single GGUF file so you can run it on a laptop CPU without any GPU.
+
+## Model Description
+
+`Nanthasit/sakthai-coder-1.5b` is a fine-tuned **Qwen2.5-Coder-1.5B-Instruct** model optimized for:
+- Code generation and completion
+- Bug fixing and small refactors
+- Tool/function call JSON generation
+- Offline CPU inference with `llama.cpp`
+
+Quantized to **GGUF Q4_K_M** for low-memory deployment while keeping usable output quality. The model is trained on a mix of code-oriented instruction data plus the SakThai combined tool-format corpus.
+
+## How to Use
+
+### 1) llama.cpp CLI
+
+```bash
+./llama-server -m qwen2.5-coder-1.5b-instruct-q4_k_m.gguf --n-gpu-layers 0 -c 4096 --temp 0.2 -ngl 0
+```
+
+### 2) Python completion client
+
+```python
+import requests
+
+response = requests.post(
+    "http://localhost:8080/completion",
+    json={
+        "prompt": "Write a Python binary search for a sorted list:",
+        "n_predict": 512,
+        "temperature": 0.2,
+        "top_p": 0.9,
+    },
+)
+print(response.json()["content"])
+```
+
+### 3) With `llama-cpp-python`
+
+```python
+from llama_cpp import Llama
+
+llm = Llama(
+    model_path="qwen2.5-coder-1.5b-instruct-q4_k_m.gguf",
+    n_ctx=4096,
+    n_threads=4,
+)
+
+out = llm(
+    "Write a Python decorator that retries a function 3 times.",
+    max_tokens=512,
+    temperature=0.2,
+    top_p=0.9,
+)
+print(out["choices"][0]["text"])
+```
+
+### Hardware
+
+- **CPU-only:** comfortable on modern laptops; expect ~8–11 tok/s on 2 threads.
+- **No GPU required:** GGUF Q4_K_M keeps memory under ~1.2 GB.
+- **Tip:** provide explicit instructions and a `<tools>` block when you want tool-calling JSON outputs.
+
+## Benchmarks
+
+Verified with `llama.cpp Q4_K_M` on CPU. Each item is run from repo-local eval artifacts and SakThai trust-pass checks.
+
+| Task | Metric | Value | Notes |
+|:-----|:------|:-----:|:------|
+| Tool Calling | Valid JSON rate | 100% | requires proper `<tools>` prompt format |
+| Tool Selection | Selection accuracy | 91.2% | SakThai Bench v2, multi-set scorer |
+| Code: factorial | pass | true | verified |
+| Code: debugging | pass | true | verified |
+| Code: async_explain | pass | true | verified |
+| Code: refactor | pass | true | verified |
+| Code: primes | pass | true | verified |
+| MBPP reference | pass@1 | 71.2% | base-model reference point |
+| Speed (CPU) | throughput | ~9–10 tok/s | 1.1 GB GGUF, 2 threads |
+
+**Known weakness:** bug-finding tasks that depend on noticing intentional logic errors may still pass through incorrect code, so review outputs for critical changes.
+
+## Training Details
+
+| Parameter | Value |
+|-----------|-------|
+| Base model | `Qwen/Qwen2.5-Coder-1.5B-Instruct` |
+| Training data | `sakthai-combined-v6`, `sakthai-combined-v7`, `sakthai-bench-v2`, `sakthai-irrelevance-supplement` |
+| License | Apache 2.0 |
+| Hardware | Free CPU/Colab sessions |
+| Budget | $0 |
+| Optimizer | AdamW |
+| Learning rate | 5e-5 with warmup |
+| Epochs | 3 |
+| Batch size | 8 |
+| GGUF quant | Q4_K_M via llama.cpp |
+
+## Limitations
+
+- Small 1.5B model; complex reasoning and large refactors can still hallucinate.
+- Tool calling is strongest when a strict `<tools>` prompt block is present; without it, the model may answer directly instead of emitting a call.
+- Quantization trades some precision for CPU usability; if GPU memory is available, prefer higher-precision formats.
+- Outputs should be reviewed for correctness, especially for security-sensitive code paths.
+
+## Citation
+
+```bibtex
+@misc{sakthai-coder-1.5b,
+  title  = {SakThai Coder 1.5B: Code Generation and Tool Calling on CPU},
+  author = {Nanthasit},
+  year   = {2026},
+  url    = {https://huggingface.co/Nanthasit/sakthai-coder-1.5b}
+}
+```
+
+## Community & Support
+
+- Issues and feedback: open a discussion on the [model page](https://huggingface.co/Nanthasit/sakthai-coder-1.5b).
+- Related: see the [SakThai Model Family](https://huggingface.co/collections/Nanthasit/sakthai-model-family-6a64745450b12d421c1f9f02).
+
+---
+
+*Built with love, tears, and zero budget.*