docs: v4 README

README.md

@@ -0,0 +1,84 @@
+---
+base_model: unsloth/functiongemma-270m-it
+license: apache-2.0
+language: en
+library_name: transformers
+tags:
+- ndp
+- tool-calling
+- function-calling
+- mcp
+- unsloth
+- lora
+- functiongemma
+- google-aligned
+- v4
+- dataset-A
+---
+
+# shazzadulimun/ndp-tool-functiongemma-270m-A-v4
+
+**v4: Google-aligned data shape** — the breakthrough fix for the
+FunctionGemma 270M null-arg-spam problem.
+
+## What changed vs v1/v2/v3
+
+Earlier versions trained on data that didn't match FunctionGemma's
+pretrained expectations. Diagnosis (2026-05-27 post-mortem):
+
+| Aspect | Google's docs say... | v1/v2/v3 had... | v4 fixes to... |
+|---|---|---|---|
+| System role | `developer` | `system` | `developer` |
+| System prompt | one sentence | 4 paragraphs of "tool-call discipline" | one sentence |
+| `<think>` blocks | NONE (FG is direct prompt→call) | enabled | **stripped** |
+| Chat template | FG native | Hermes (v3) or native (v1/v2) | FG native |
+
+## Smoke test results (greedy, 200 new tokens)
+
+| Prompt | Verdict |
+|---|---|
+| `list_organizations(server='global')` | minor: 1 null leak (`name_filter:None`) |
+| `list_organizations(name_filter='water', server='global')` | ✅ CLEAN |
+| `search_datasets(climate, limit=5)` 14-param tool | ❌ still null spam |
+| `get_dataset_details(...)` | ✅ CLEAN |
+| weather (refusal) | ✅ natural refusal |
+
+**3/5 clean** — up from 0/5 in v3. The remaining failure mode is purely
+**model capacity** for tools with very wide arg-schemas (>10 params).
+For 1-3 param tools, v4 is production-quality.
+
+## Files
+
+- `merged_16bit/` — safetensors
+- `lora/` — LoRA adapter only
+
+## Usage
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+mid = "shazzadulimun/ndp-tool-functiongemma-270m-A-v4"
+tok = AutoTokenizer.from_pretrained(mid, subfolder="merged_16bit")
+mdl = AutoModelForCausalLM.from_pretrained(mid, subfolder="merged_16bit", device_map="auto")
+
+# Note: use role "developer" (NOT "system"), as Google's docs require
+messages = [
+    {"role": "developer", "content": "You are a model that can do function calling with the following functions"},
+    {"role": "user", "content": "..."},
+]
+prompt = tok.apply_chat_template(messages, tools=[...], add_generation_prompt=True, tokenize=False)
+```
+
+Output format is FG native: `<start_function_call>call:NAME{key:<escape>val<escape>}<end_function_call>`.
+
+## Training
+
+- 1087 rows (987 tool + 100 refusal), Dataset A v4-aligned
+- LoRA r=64 alpha=128, 3 epochs, batch=16, lr=2e-4
+- Train loss: 0.25
+- Training time: ~3 min on 1× H200
+
+## Related repos
+
+- `shazzadulimun/ndp-tool-functiongemma-270m-A`         — v1 native FG
+- `shazzadulimun/ndp-tool-functiongemma-270m-A-v2`      — v2-clean native FG
+- `shazzadulimun/ndp-tool-functiongemma-270m-A-v2-hermes` — Hermes template variant (still leaks)