docs: fix badges, add interactive widget, merge script, and complete retail text2sql docs

README.md

@@ -6,16 +6,19 @@ tags:
   - text-to-sql
   - retail
   - ecommerce
-  - pos
-  - indonesia
+  - point-of-sale
   - indonesian
+  - bahasa-indonesia
   - qwen2.5-coder
   - lora
-  - sql-generation
+  - sql
 language:
   - id
   - en
 license: apache-2.0
+widget:
+  - text: "<|im_start|>system\nKamu adalah database architect dan ahli SQL yang menerjemahkan pertanyaan bahasa Indonesia ke SQL query berdasarkan skema database yang disediakan.<|im_end|>\n<|im_start|>user\n### Skema Database:\nCREATE TABLE produk (\n    id_produk VARCHAR(10) PRIMARY KEY,\n    nama_produk VARCHAR(100),\n    kategori VARCHAR(50),\n    harga DECIMAL(12, 2),\n    stok INT\n);\n\n### Pertanyaan:\nTampilkan daftar produk kategori 'Makanan' dengan stok kurang dari 20 unit, diurutkan dari stok paling sedikit.\n\n### SQL:<|im_end|>\n<|im_start|>assistant\n"
+    example_title: "Filter Stok Produk"
 ---
 
 <div align="center">
@@ -24,102 +27,121 @@ license: apache-2.0
 
 **Model Spesialis Text-to-SQL Berbahasa Indonesia untuk Domain Ritel, POS, & E-Commerce**
 
-[![Base Model](https://img.shields.io/badge/Base%20Model-Qwen2.5--Coder--7B--Instruct-blue?style=flat-square)](https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct)
-[![PEFT](https://img.shields.io/badge/FineTuned-PEFT%20LoRA-orange?style=flat-square)](https://github.com/huggingface/peft)
-[![Language](https://img.shields.io/badge/Language-Indonesian%20%7C%20English-green?style=flat-square)](#)
-[![Task](https://img.shields.io/badge/Task-Text--to--SQL-purple?style=flat-square)](#)
-[![License](https://img.shields.io/badge/License-Apache%202.0-yellow?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
+[![Base Model](https://img.shields.io/badge/Base_Model-Qwen2.5--Coder--7B--Instruct-blue?style=flat-square)](https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct)
+[![PEFT](https://img.shields.io/badge/FineTuned-PEFT_LoRA-orange?style=flat-square)](https://github.com/huggingface/peft)
+[![Language](https://img.shields.io/badge/Language-Indonesian_%7C_English-green?style=flat-square)](#)
+[![Task](https://img.shields.io/badge/Task_Type-Text2SQL-purple?style=flat-square)](#)
+[![License](https://img.shields.io/badge/License-Apache_2.0-yellow?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
 
 </div>
 
 ---
 
+## 📋 Daftar Isi
+- [Deskripsi Model](#-deskripsi-model)
+- [Fitur Unggulan](#-fitur-unggulan)
+- [Konfigurasi LoRA](#-konfigurasi-lora)
+- [Panduan Penggunaan (Inference)](#-panduan-penggunaan-inference)
+  - [Opsi A: Standar (Transformers + PEFT)](#opsi-a-standar-transformers--peft)
+  - [Opsi B: Hemat Memori (4-bit Quantization)](#opsi-b-hemat-memori-4-bit-quantization)
+  - [Opsi C: Merge Adapter ke Base Model (Untuk vLLM / Ollama / GGUF)](#opsi-c-merge-adapter-ke-base-model)
+- [Contoh Kasus & Output](#-contoh-kasus--output)
+- [Format Prompt Rekomendasi](#-format-prompt-rekomendasi)
+- [Praktik Keamanan & Batasan](#-praktik-keamanan--batasan)
+- [Sitasi & Kontak](#-sitasi--kontak)
+
+---
+
 ## 📌 Deskripsi Model
 
-**Qwen2.5-Coder-7B-Retail-Text2SQL-ID** adalah LoRA fine-tuned adapter dari model fondasi **Qwen/Qwen2.5-Coder-7B-Instruct**. Model ini dilatih khusus untuk memahami terminologi bisnis ritel Indonesia (seperti *omzet, retur, stok kritis, diskon, margin kotor, cabang, kasir, metode pembayaran QRIS/tunai*) dan mengubah instruksi bahasa alami menjadi kueri SQL yang akurat dan siap dieksekusi.
+**Qwen2.5-Coder-7B-Retail-Text2SQL-ID** adalah LoRA fine-tuned adapter dari model fondasi **Qwen/Qwen2.5-Coder-7B-Instruct**. Model ini dilatih khusus untuk memahami terminologi bisnis dan operasional ritel Indonesia (seperti *omzet, retur barang, stok menipis, diskon promo, margin kotor, cabang toko, kasir, metode pembayaran QRIS/tunai/transfer*) dan mengonversinya menjadi kueri SQL yang presisi dan efisien.
 
-### ✨ Fitur Unggulan
-- 🇮🇩 **Pemahaman Konteks Lokal**: Memahami gaya bahasa dan istilah operasional ritel Indonesia.
-- 🔗 **Kompleksitas Multi-Table**: Mampu melakukan kueri dengan multi-table `JOIN`, agregasi (`GROUP BY`, `HAVING`), window function, dan subqueries.
-- ⚡ **LoRA Adapter Ringan**: Ukuran adapter di bawah 100MB, hemat VRAM, serta mudah diintegrasikan ke sistem POS atau dashboard analitik yang sudah ada.
-- 🗄️ **Multi-Dialect SQL**: Kompatibel dengan sintaks standar PostgreSQL, MySQL, dan SQLite.
+### 🌟 Fitur Unggulan
+- 🇮🇩 **Pemahaman Konteks Lokal**: Mengerti bahasa alami percakapan bisnis ritel Indonesia tanpa perlu translasi ke bahasa Inggris.
+- 🔗 **Kemampuan Multi-Table Relational**: Menguasai pembentukan klausa `JOIN` antar tabel transaksi, detail barang, pelanggan, kasir, dan master cabang.
+- 📊 **Kueri Analitik & Agregasi**: Mampu menghasilkan query `GROUP BY`, `HAVING`, fungsi jendela (`ROW_NUMBER()`, `RANK()`), serta kalkulasi subtotal/omzet secara tepat.
+- 🗄️ **Kompatibilitas Dialek SQL**: Mendukung sintaks standar ANSI SQL yang kompatibel dengan PostgreSQL, MySQL, MariaDB, dan SQLite.
+- ⚡ **Adapter Ringan**: Bobot adapter di bawah 100MB sehingga fleksibel dipasang di berbagai infrastruktur on-premise maupun cloud.
 
 ---
 
-## ⚙️ Detail Konfigurasi LoRA
+## ⚙️ Konfigurasi LoRA
+
+Berdasarkan metadata adapter:
 
-| Parameter | Nilai | Keterangan |
+| Parameter | Nilai | Penjelasan |
 | :--- | :--- | :--- |
-| **Base Model** | `Qwen/Qwen2.5-Coder-7B-Instruct` | 7B Parameter instruction model |
-| **LoRA Rank ($r$)** | `16` | Representasi subspace |
-| **LoRA Alpha ($\alpha$)** | `32` | Scaling factor |
-| **LoRA Dropout** | `0.05` | Regularisasi pencegah overfitting |
-| **Target Modules** | `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj` | Seluruh linear projection |
-| **Tipe Task** | `CAUSAL_LM` | Next-token prediction |
+| **Base Model** | `Qwen/Qwen2.5-Coder-7B-Instruct` | 7B SOTA instruction code model |
+| **LoRA Rank ($r$)** | `16` | Dimensi subspace adaptasi |
+| **LoRA Alpha ($\alpha$)** | `32` | Faktor pengali bobot gradien |
+| **LoRA Dropout** | `0.05` | Regularisasi untuk mencegah overfitting |
+| **Target Modules** | `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj` | Seluruh proyeksi linear modul attention & MLP |
+| **Task Type** | `CAUSAL_LM` | Model generasi autoregresif |
 
 ---
 
-## 🚀 Panduan Penggunaan (Quickstart)
+## 🚀 Panduan Penggunaan (Inference)
 
-### 1. Instalasi Dependensi
+### Dependensi
 ```bash
 pip install torch transformers peft accelerate bitsandbytes
 ```
 
-### 2. Inferensi Python (4-Bit Quantized untuk VRAM Hemat)
+### Opsi A: Standar (Transformers + PEFT)
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+BASE_ID = "Qwen/Qwen2.5-Coder-7B-Instruct"
+ADAPTER_ID = "rizalbasri/qwen2.5-coder-7b-retail-text2sql-id"
+
+tokenizer = AutoTokenizer.from_pretrained(BASE_ID, trust_remote_code=True)
+base_model = AutoModelForCausalLM.from_pretrained(
+    BASE_ID,
+    torch_dtype=torch.bfloat16,
+    device_map="auto",
+    trust_remote_code=True
+)
+model = PeftModel.from_pretrained(base_model, ADAPTER_ID)
+model.eval()
+```
+
+### Opsi B: Hemat Memori (4-bit Quantization)
+Gunakan opsi ini jika Anda menjalankan model pada GPU dengan VRAM terbatas (8GB - 16GB):
 
 ```python
 import torch
 from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
 from peft import PeftModel
 
-BASE_MODEL = "Qwen/Qwen2.5-Coder-7B-Instruct"
-ADAPTER_MODEL = "rizalbasri/qwen2.5-coder-7b-retail-text2sql-id"
+BASE_ID = "Qwen/Qwen2.5-Coder-7B-Instruct"
+ADAPTER_ID = "rizalbasri/qwen2.5-coder-7b-retail-text2sql-id"
 
-# 1. Konfigurasi 4-bit (jalan di GPU 8GB - 16GB)
 bnb_config = BitsAndBytesConfig(
     load_in_4bit=True,
     bnb_4bit_quant_type="nf4",
     bnb_4bit_compute_dtype=torch.bfloat16
 )
 
-tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True)
+tokenizer = AutoTokenizer.from_pretrained(BASE_ID, trust_remote_code=True)
 base_model = AutoModelForCausalLM.from_pretrained(
-    BASE_MODEL,
+    BASE_ID,
     quantization_config=bnb_config,
     device_map="auto",
     trust_remote_code=True
 )
 
-# 2. Pasang Adapter LoRA
-model = PeftModel.from_pretrained(base_model, ADAPTER_MODEL)
+model = PeftModel.from_pretrained(base_model, ADAPTER_ID)
 model.eval()
 
-# 3. Siapkan Prompt & Skema Database
-system_prompt = (
-    "Kamu adalah database architect dan ahli SQL. Tugasmu adalah membaca skema database "
-    "dan menerjemahkan pertanyaan pengguna dalam bahasa Indonesia menjadi kueri SQL yang valid."
-)
-
+# Definisi Skema & Prompt
 schema = """
-CREATE TABLE cabang (
-    id_cabang VARCHAR(10) PRIMARY KEY,
-    nama_cabang VARCHAR(100),
-    kota VARCHAR(50)
-);
-
-CREATE TABLE produk (
-    id_produk VARCHAR(10) PRIMARY KEY,
-    nama_produk VARCHAR(100),
-    kategori VARCHAR(50),
-    harga_jual DECIMAL(12, 2),
-    stok INT
-);
-
 CREATE TABLE transaksi (
     id_transaksi VARCHAR(20) PRIMARY KEY,
-    tanggal TIMESTAMP,
-    id_cabang VARCHAR(10) REFERENCES cabang(id_cabang),
+    tanggal DATE,
+    id_cabang VARCHAR(10),
     total_bayar DECIMAL(12, 2),
     metode_bayar VARCHAR(30)
 );
@@ -127,15 +149,17 @@ CREATE TABLE transaksi (
 CREATE TABLE detail_transaksi (
     id_detail VARCHAR(20) PRIMARY KEY,
     id_transaksi VARCHAR(20) REFERENCES transaksi(id_transaksi),
-    id_produk VARCHAR(10) REFERENCES produk(id_produk),
+    id_produk VARCHAR(10),
+    nama_produk VARCHAR(100),
+    kategori VARCHAR(50),
     jumlah INT,
-    subtotal DECIMAL(12, 2)
+    harga_satuan DECIMAL(12, 2)
 );
 """
 
-user_question = "Berapa total omzet per kategori produk untuk cabang Kota Bandung selama bulan Oktober 2024?"
+user_question = "Berapa total pendapatan dari metode pembayaran QRIS per kategori barang di bulan Januari 2024?"
 
-prompt = f"""### Skema Database:
+prompt_content = f"""### Skema Database:
 {schema.strip()}
 
 ### Pertanyaan:
@@ -144,17 +168,15 @@ prompt = f"""### Skema Database:
 ### SQL:"""
 
 messages = [
-    {"role": "system", "content": system_prompt},
-    {"role": "user", "content": prompt}
+    {
+        "role": "system",
+        "content": "Kamu adalah database architect dan ahli SQL yang menerjemahkan pertanyaan bahasa Indonesia ke SQL query berdasarkan skema database yang disediakan."
+    },
+    {"role": "user", "content": prompt_content}
 ]
 
-formatted_prompt = tokenizer.apply_chat_template(
-    messages,
-    tokenize=False,
-    add_generation_prompt=True
-)
-
-inputs = tokenizer(formatted_prompt, return_tensors="pt").to(model.device)
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(text, return_tensors="pt").to(model.device)
 
 with torch.no_grad():
     outputs = model.generate(
@@ -165,53 +187,106 @@ with torch.no_grad():
         pad_token_id=tokenizer.eos_token_id
     )
 
-generated_sql = tokenizer.decode(outputs[0][len(inputs.input_ids[0]):], skip_special_tokens=True)
-print("=== HASIL QUERY SQL ===")
-print(generated_sql)
+hasil_sql = tokenizer.decode(outputs[0][len(inputs.input_ids[0]):], skip_special_tokens=True)
+print(hasil_sql)
+```
+
+### Opsi C: Merge Adapter ke Base Model
+Jika Anda ingin mengekspor model menjadi standalone model untuk inferensi berkecepatan tinggi dengan **vLLM**, atau dikonversi ke **GGUF / Ollama**:
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+BASE_ID = "Qwen/Qwen2.5-Coder-7B-Instruct"
+ADAPTER_ID = "rizalbasri/qwen2.5-coder-7b-retail-text2sql-id"
+OUTPUT_DIR = "./qwen2.5-coder-7b-retail-text2sql-id-merged"
+
+print("Memuat base model...")
+base_model = AutoModelForCausalLM.from_pretrained(
+    BASE_ID,
+    torch_dtype=torch.float16,
+    device_map="cpu",
+    trust_remote_code=True
+)
+tokenizer = AutoTokenizer.from_pretrained(BASE_ID, trust_remote_code=True)
+
+print("Memasang LoRA adapter...")
+model = PeftModel.from_pretrained(base_model, ADAPTER_ID)
+
+print("Menggabungkan bobot (merging)...")
+merged_model = model.merge_and_unload()
+
+print(f"Menyimpan model hasil merge ke {OUTPUT_DIR}...")
+merged_model.save_pretrained(OUTPUT_DIR, safe_serialization=True)
+tokenizer.save_pretrained(OUTPUT_DIR)
+print("Selesai! Model siap digunakan pada vLLM atau dikonversi ke GGUF.")
 ```
 
 ---
 
 ## 💡 Contoh Kasus & Output
 
-### Kasus 1: Filter Stok Kritis
-- **Pertanyaan:** *"Tampilkan produk yang stoknya tersisa kurang dari 10 unit dan urutkan dari yang paling sedikit."*
+### 1. Manajemen Stok & Peringatan Reorder
+- **Pertanyaan:** *"Tampilkan produk apa saja yang sisa stoknya kurang dari 15 buah dan urutkan dari yang paling sedikit."*
 - **Output SQL:**
 ```sql
 SELECT id_produk, nama_produk, kategori, stok
 FROM produk
-WHERE stok < 10
+WHERE stok < 15
 ORDER BY stok ASC;
 ```
 
-### Kasus 2: Top Customer Berdasarkan Nilai Transaksi
-- **Pertanyaan:** *"Siapa 10 pelanggan dengan total belanja terbesar pada metode pembayaran QRIS?"*
+### 2. Multi-Table JOIN & Analisis Performa Cabang
+- **Pertanyaan:** *"Tampilkan 5 cabang dengan total penjualan tertinggi beserta nama kotanya pada kuartal 1 tahun 2024."*
 - **Output SQL:**
 ```sql
 SELECT 
-    t.id_pelanggan, 
-    p.nama_pelanggan, 
-    SUM(t.total_bayar) AS total_belanja
-FROM transaksi t
-JOIN pelanggan p ON t.id_pelanggan = p.id_pelanggan
-WHERE t.metode_bayar = 'QRIS'
-GROUP BY t.id_pelanggan, p.nama_pelanggan
-ORDER BY total_belanja DESC
-LIMIT 10;
+    c.id_cabang, 
+    c.nama_cabang, 
+    c.kota, 
+    SUM(t.total_bayar) AS total_omzet
+FROM cabang c
+JOIN transaksi t ON c.id_cabang = t.id_cabang
+WHERE t.tanggal BETWEEN '2024-01-01' AND '2024-03-31'
+GROUP BY c.id_cabang, c.nama_cabang, c.kota
+ORDER BY total_omzet DESC
+LIMIT 5;
+```
+
+---
+
+## 📝 Format Prompt Rekomendasi
+
+Gunakan struktur prompt berikut untuk konsistensi akurasi tertinggi:
+
+```text
+<|im_start|>system
+Kamu adalah database architect dan ahli SQL yang menerjemahkan pertanyaan bahasa Indonesia ke SQL query berdasarkan skema database yang disediakan.<|im_end|>
+<|im_start|>user
+### Skema Database:
+[Letakkan DDL atau deskripsi tabel di sini]
+
+### Pertanyaan:
+[Pertanyaan operasional / bisnis ritel dalam bahasa Indonesia]
+
+### SQL:<|im_end|>
+<|im_start|>assistant
 ```
 
 ---
 
-## 🔒 Praktik Keamanan & Batasan (Security & Limitations)
+## 🛡️ Praktik Keamanan & Batasan
 
-1. **Read-Only Privilege**: Sangat disarankan menjalankan query hasil generasi AI menggunakan database user dengan hak akses **hanya baca (`SELECT`)**.
-2. **SQL Injection Defense**: Jangan langsung memasukkan kueri ke eksekutor database tanpa sanitasi bila melibatkan parameter dinamis dari input web publik.
-3. **Validasi Skema**: Berikan skema tabel sejelas mungkin (termasuk tipe data dan relasi foreign key) di dalam prompt agar hasil kueri tidak mengalami halusinasi nama kolom.
+1. **Akses Read-Only Database**: Kueri hasil AI harus dieksekusi dengan akun database berizin `SELECT` saja untuk mencegah risiko modifikasi data tanpa sengaja.
+2. **Kueri Ambigu**: Pastikan skema tabel mencantumkan relasi `FOREIGN KEY` jika pertanyaan memerlukan penggabungan multi-tabel yang kompleks.
+3. **Execution Boundary**: Selalu gunakan query timeout limit (misalnya 10-30 detik) pada database engine analitik Anda untuk mencegah bottleneck beban kueri.
 
 ---
 
-## 📜 Lisensi & Atribusi
+## 📄 Lisensi & Atribusi
 
-- **Lisensi:** [Apache-2.0](https://opensource.org/licenses/Apache-2.0)
-- **Base Model:** [Qwen2.5-Coder-7B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct) oleh Alibaba Cloud.
-- **Dilatih oleh:** [rizalbasri](https://huggingface.co/rizalbasri)
+- **Lisensi Kode & Model**: [Apache License 2.0](https://opensource.org/licenses/Apache-2.0)
+- **Base Model**: [Qwen2.5-Coder-7B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct) oleh Alibaba Cloud
+- **Pengembang**: [rizalbasri](https://huggingface.co/rizalbasri)