prayphnadeak/cadas-besemah

🤖 CADAS BESEMAH — Chatbot AI Bahasa Besemah & Agen Text-to-SQL BPS Kota Pagar Alam

CADAS BESEMAH adalah sistem Web Dashboard Interaktif dan API Webhook WhatsApp (Whatauto) yang mengintegrasikan seluruh repositori dan pustaka di dalam Virtual Environment (venv Python 3.12) serta siap di-deploy ke Hugging Face Spaces (sdk: docker):

1. corpus_besemah-main (prayphnadeak/corpus_besemah) → besemah_corpus_engine.py:
   • Mengintegrasikan 6.876 entri kamus (dictionary.json) dan 31.424 pasangan instruksi (train.jsonl & validation.jsonl) ke dalam indeks hibrida berbasis RapidFuzz (C++ Fuzzy Matching), rank_bm25 (BM25Okapi Sentence Retrieval), dan SQLite (bps_pagaralam.db).
   • Mendukung normalisasi diakritik (é → e), pencarian sinonim, terjemahan kalimat kata-demi-kata, dan toleransi salah ketik (typo).
2. from-text-to-sql-agent (algonacci/from-text-to-sql-agent) → text_to_sql_agent.py:
   • Menggunakan sqlglot untuk memvalidasi AST sintaks SQL dan menerapkan Read-Only Guardrail (hanya mengizinkan kueri SELECT pada tabel resmi BPS).
   • Menggunakan pandas, pydantic, dan python-dotenv untuk eksekusi kueri statistik SQLite BPS Kota Pagar Alam secara terstruktur.
   • Mencakup 5 tabel utama: Kependudukan per Kecamatan, 14 Indikator Strategis Ekonomi/IPM/Kemiskinan/TPT, Fasilitas Pendidikan, Fasilitas Kesehatan, serta Pertanian Kopi Robusta & Pariwisata, lengkap dengan router tautan Tabel Dinamis Resmi BPS Kota Pagar Alam.

---

💻 Menjalankan & Menguji secara Lokal dengan venv

Seluruh paket di dalam folder venv telah terhubung langsung dengan modul aplikasi:

1. Jalankan Server Lokal via venv

Klik dua kali run_venv.bat atau jalankan di PowerShell:

.\venv\Scripts\python.exe app.py

Buka browser di http://localhost:7860.

2. Jalankan Pengujian Otomatis (unittest) via venv

.\venv\Scripts\python.exe test_app.py

---

🚀 Cara Deploy ke Hugging Face Spaces

Anda dapat men-deploy repositori ini ke Hugging Face Spaces menggunakan salah satu dari 2 cara berikut:

Cara 1: Deploy Otomatis 1-Baris Perintah via venv (deploy_hf.py)

Karena huggingface_hub sudah terinstal di venv, Anda dapat langsung mengunggah dan men-deploy seluruh proyek ke Hugging Face Spaces dari terminal:

.\venv\Scripts\python.exe deploy_hf.py --repo-id <USERNAME_HF_ANDA>/cadas-besemah --token <HF_WRITE_TOKEN_ANDA>

Skrip deploy_hf.py akan otomatis membuat Space ber-SDK Docker (jika belum ada) dan mengunggah seluruh kode, template, modul agen, serta database SQLite ke Hugging Face Spaces.

Cara 2: Upload Manual lewat Browser Hugging Face

1. Buat Space baru di https://huggingface.co/new-space dengan SDK Docker (Blank).
2. Unggah berkas berikut:
   • app.py
   • text_to_sql_agent.py
   • besemah_corpus_engine.py
   • Dockerfile (menggunakan /opt/venv Python 3.12 yang identik dengan venv lokal)
   • requirements.txt
   • README.md
   • besemah_simple_qa.json
   • bps_pagaralam.db
   • Folder templates/index.html

---

📱 Cara Menghubungkan ke WhatsApp via Aplikasi Whatauto

Setelah status Hugging Face Space Anda Running:

1. Salin URL Webhook Space Anda:

   https://<username-anda>-<nama-space-anda>.hf.space/whatauto-webhook
   

2. Buka aplikasi Whatauto di Android → masuk ke Build Your Bot → Server API / Custom Server.
3. Aktifkan Server API, masukkan URL Webhook di atas pada kolom Server URL, dan pilih metode POST.
4. Nyalakan Auto Reply On di halaman utama Whatauto.

---

🔌 Daftar Endpoint API

Metode	Endpoint	Deskripsi
GET	/	Web Dashboard Interaktif (Simulator WhatsApp, Kamus Besemah, Tabel BPS, Panduan)
POST	/whatauto-webhook	Endpoint Webhook utama untuk aplikasi Whatauto ({"reply": "..."})
POST	/api/chat	Endpoint API untuk simulator chatbot (mengembalikan balasan & sql_query tervalidasi)
POST	/api/sql	Endpoint eksekusi kueri SQL SELECT kustom dengan guardrail sqlglot
GET	/api/dictionary?q=...	Pencarian kamus Bahasa Besemah (q, limit, offset)
GET	/api/bps	Seluruh dataset tabel statistik BPS Kota Pagar Alam & DDL skema database
GET	/api/stats / /health	Health check server, metrik indeks BM25/RapidFuzz, dan ringkasan database