validation-semantic 1.1.4

Library pendeteksi kalimat atau kata untuk validasi semantik input menggunakan LLM

🤖 Library Semantic Validation Dengan Gemini API

validation_semantic adalah library validasi semantik yang cepat, aman, dan cerdas — dibangun sepenuhnya dengan Rust dan didukung oleh model Gemini dari Google AI Studio.

Library ini tidak hanya memeriksa validitas data secara sintaksis (misalnya format email atau nomor telepon), tetapi juga melakukan analisis semantik untuk memahami makna dan konteks dari input pengguna. Dengan integrasi Gemini API, proses validasi menjadi lebih kontekstual dan adaptif terhadap berbagai jenis data maupun bahasa.

Berbeda dari validator konvensional, validation_semantic berfokus pada pemahaman arti dan tujuan data, bukan sekadar pola teks. Sebagai contoh, library ini dapat membedakan apakah sebuah input lebih sesuai dikategorikan sebagai nama institusi, alamat email, deskripsi, atau teks naratif — menghasilkan validasi yang jauh lebih presisi dan bermakna.

💡 Untuk versi Python, library ini dapat digunakan di lingkungan mana pun (baik server-side maupun client-side). Sedangkan untuk versi JavaScript / TypeScript, library ini dirancang khusus untuk berjalan di sisi front-end (client-side) — ideal untuk aplikasi web dengan React atau Next yang memerlukan validasi cerdas langsung di browser.

⚠️ Catatan: Library ini masih dalam tahap eksperimental. Fitur, API, dan hasil validasi dapat berubah pada versi berikutnya seiring dengan pengujian dan peningkatan performa. 🧩 Masukan dari pengembang sangat dibutuhkan — saran, laporan bug, dan kontribusi Anda sangat membantu dalam mengembangkan dan menstabilkan library ini.

---

🧠 Catatan Penelitian:

Pustaka ini dikembangkan sebagai bagian dari proyek penelitian akademis. Pengembang didorong untuk mencobanya dan memberikan umpan balik mengenai kinerja dan kemudahan penggunaannya. Untuk informasi selengkapnya, lihat bagian 📊 Permintaan Partisipasi Dan Umpan Balik Riset di bawah ini.

---

🌍 Dukungan Multiplatform

---

Kelebihan utama validation_semantic terletak pada desain modular dan interoperabilitas lintas platform melalui bindings:

• 🧩 WebAssembly (WASM) — memungkinkan integrasi di frontend seperti React atau Vue dengan performa tinggi langsung di browser.
• 🐍 Python (via PyO3 / Maturin) — ideal untuk backend services, data validation pipelines, atau machine learning preprocessing.
• 🔧 Dukungan untuk binding lain seperti Kotlin sedang dalam tahap pengembangan.

Dengan kombinasi kecepatan Rust dan kecerdasan Gemini, validation_semantic menghadirkan sistem validasi modern yang kontekstual, efisien, dan mudah diintegrasikan ke berbagai proyek.

---

📑 Daftar Isi

1. 🌟 Fitur Utama

2. 🚀 Memulai

3. ⚛️ Menggunakan Library di React (Vite)

   • 🧩 Instalasi Library dan Plugin Pendukung
   • ⚙️ Konfigurasi Vite
   • 🚀 Gunakan Modul WASM di React
   • 🧾 Contoh Output
   • 📘 Ringkasan Fungsi Utama

4. 🐍 Instalasi untuk Python

   • 🔑 Konfigurasi API Key
   • 🚀 Cara Penggunaan untuk Python
   • 📦 Validasi Banyak Input Sekaligus (Batch Validation)

5. 🧩 Jenis Input yang Dapat Divalidasi

6. 🤝 Kontribusi

7. Research Participation & Feedback

8. 📄 Lisensi

9. Changelog

---

🌟 Fitur Utama

• Core Logic dalam Rust: Mesin validasi semantik yang cepat, aman, dan efisien, dibangun di atas fondasi Rust.
• Validasi Berbasis Aturan: Terapkan seperangkat aturan yang dapat dikonfigurasi untuk memeriksa integritas dan konsistensi semantik data Anda.
• Deteksi Anomali: Mudah mengidentifikasi pola atau nilai data yang tidak sesuai dengan ekspektasi semantik Anda.
• API yang Fleksibel: Dirancang untuk mudah diekspos melalui bindings ke berbagai bahasa dan lingkungan pemrograman.
• Laporan Detail: Dapatkan laporan validasi yang jelas dan informatif.
• Siap untuk Cross-Platform: Digunakan di server, desktop, maupun browser.

---

🚀 Memulai

validation_semantic dirancang agar dapat digunakan lintas platform — Anda dapat memanfaatkan core logic-nya yang ditulis dalam Rust melalui binding ke berbagai bahasa dan lingkungan pemrograman.

Saat ini, library ini dapat digunakan di dua platform utama:

• Frontend: React (Vite) menggunakan WebAssembly (WASM)
• Backend / Desktop: Python (via PyO3 / Maturin)

---

⚛️ Menggunakan Library di React (Vite) / Next JS

Library ini dapat digunakan di React (Vite) dengan memanfaatkan WebAssembly (WASM) yang dibangun menggunakan Rust. Langkah-langkah berikut menjelaskan cara instalasi dan penggunaannya.

Untuk Next JS, sudah otomatis mendukung WASM — tidak memerlukan konfigurasi tambahan seperti di Vite. Cukup gunakan komponen WasmProvider untuk membungkus tag lain.

⚠️ Library ini hanya bisa digunakan pada file yang di bagian atasnya memiliki "use client".

Kunjungi repository React-Library-Semantic-Validation di: 👉 https://github.com/herros27/React-Library-Semantic-Validation/pkgs/npm/validation_semantic

---

🧩 1️⃣ Instalasi Library dan Plugin Pendukung

# Instal library utama
npm install validation_semantic

# Instal plugin WASM untuk Vite
npm install vite-plugin-wasm vite-plugin-top-level-await

Plugin ini diperlukan agar Vite bisa memuat file .wasm dengan benar dan mendukung penggunaan await di level atas module.

---

⚙️ 2️⃣ Konfigurasi Vite

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import wasm from "vite-plugin-wasm";
import topLevelAwait from "vite-plugin-top-level-await";

export default defineConfig({
  plugins: [
    react(),
    wasm(), // Aktifkan dukungan untuk WebAssembly
    topLevelAwait(), // Izinkan penggunaan "await" di top-level
    tailwindcss(),
  ],
});

---

Pastikan seluruh aplikasi dibungkus oleh WasmProvider di main.tsx

// main.tsx
import { WasmProvider } from "validation_semantic";

createRoot(document.getElementById("root")!).render(
  <WasmProvider>
    <StrictMode>
      <App />
    </StrictMode>
  </WasmProvider>
);

---

Wajib: Konfigurasi Wasm Module Dengan API Key dari Google AI Studio di app.tsx (atau di dalam komponen yang berada di dalam WasmProvider)

// app.tsx
export default function App() {
  const { wasmReady, wasmModule } = useWasm();

  useEffect(() => {
    if (!wasmReady || !wasmModule) return;
    const apiKey = import.meta.env.VITE_GEMINI_API_KEY;
    wasmModule.configure(apiKey);
  }, [wasmReady, wasmModule]);

  return (
    <Router>
      <Routes>
        <Route path='/' element={<FormTestPage />} />
        <Route path='/developer' element={<FormDeveloperPage />} />
      </Routes>
    </Router>
  );
}

---

📌 Catatan Penting

wasmModule.configure(apiKey) harus dipanggil di dalam komponen yang dirender di bawah <WasmProvider>. Jika tidak, modul WebAssembly tidak akan terinisialisasi dengan benar dan fitur validasi akan gagal berfungsi.

---

🔑 Konfigurasi

Library ini memerlukan API Key dari Google AI Studio.

# Buat file .env dan buat envirovment variabel seperti di bawah:
VITE_GEMINI_API_KEY="API_KEY_ANDA"

---

🚀 3️⃣ Gunakan Modul WASM di React

import { useWasm } from "validation_semantic";

export default function Example() {
  const { wasmReady, wasmModule, error } = useWasm();

  async function runValidation() {
    if (!wasmReady || !wasmModule) {
      console.warn("WASM belum siap");
      return;
    }

    const model = wasmModule.getSupportedModels().GeminiFlashLite;

    const result = await wasmModule.validateInput(
      "PT Sinar Mentari",
      model,
      "Nama Perusahaan"
    );

    console.log(result);
  }

  if (error) console.error(error);
  else runValidation();
}

---

📋 Hasil Contoh Output (di Console)

{
  "valid": true,
  "message": "Input 'PT Sinar Mentari' adalah nama perusahaan yang valid dan umum di Indonesia."
}

---

🧠 5️⃣ Contoh Validasi Banyak Input Sekaligus (Batch Validation)

Kamu dapat melakukan validasi beberapa input sekaligus menggunakan validateInput dari modul WASM. Setiap input diproses secara asynchronous dan paralel untuk efisiensi.

import React, { useState } from "react";
import { useWasm } from "validation_semantic";

type InputType =
  | "email"
  | "institution name"
  | "company name"
  | "product name"
  | "location name"
  | "full name"
  | "title"
  | "occupation"
  | "tag"
  | "address"
  | "text area";

export default function BatchValidationExample() {
  const { wasmReady, wasmModule, error: wasmError } = useWasm();

  const [formData, setFormData] = useState<Record<InputType, string>>({
    email: "",
    "full name": "",
    address: "",
    "product name": "",
    "institution name": "",
    "company name": "",
    "location name": "",
    title: "",
    occupation: "",
    tag: "",
    "text area": "",
  });

  const [results, setResults] = useState<Record<string, any> | null>(null);
  const [loading, setLoading] = useState(false);

  // Handler perubahan input
  const handleChange = (key: InputType, value: string) => {
    setFormData((prev) => ({
      ...prev,
      [key]: value,
    }));
  };

  async function validateBatchInputs() {
    if (!wasmReady || !wasmModule) {
      alert("WASM module is not ready.");
      return;
    }
    // You can use other model like GeminiFlash, GeminiFlashLatest, Gemma
    const model = wasmModule.getSupportedModels().GeminiFlashLite;

    setLoading(true);
    try {
      const validationPromises = Object.entries(formData)
        .filter(([_, value]) => value.trim() !== "") // hanya input yang diisi
        .map(async ([inputType, inputValue]) => {
          try {
            const result = await wasmModule.validateInput(
              inputValue,
              model,
              inputType as InputType
            );
            return { inputType, inputValue, result, error: null };
          } catch (err: any) {
            return {
              inputType,
              inputValue,
              result: null,
              error: err?.message ?? "Validation error occurred.",
            };
          }
        });

      const results = await Promise.all(validationPromises);
      const batchResults = Object.fromEntries(
        results.map((r) => [
          r.inputType,
          { input: r.inputValue, result: r.result, error: r.error },
        ])
      );

      setResults(batchResults);
      console.log("Batch Validation Results:", batchResults);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div className='max-w-xl mx-auto p-4 space-y-6'>
      <h1 className='text-xl font-bold text-center'>Batch Validation Form</h1>

      {/* Form Input */}
      <div className='space-y-4'>
        {Object.keys(formData).map((key) => (
          <div key={key} className='flex flex-col'>
            <label className='font-semibold capitalize'>{key}</label>
            <input
              type='text'
              className='border border-gray-300 rounded-md p-2'
              value={formData[key as InputType]}
              onChange={(e) => handleChange(key as InputType, e.target.value)}
              placeholder={`Masukkan ${key}`}
            />
          </div>
        ))}
      </div>

      {/* Tombol Validasi */}
      <button
        onClick={validateBatchInputs}
        disabled={loading || !wasmReady}
        className='bg-blue-600 text-white px-4 py-2 rounded-md w-full disabled:opacity-50'>
        {loading ? "Validating..." : "Validate All Inputs"}
      </button>

      {/* Hasil */}
      {results && (
        <div className='mt-6 bg-gray-100 p-4 rounded-md'>
          <h2 className='font-semibold mb-2'>Validation Results:</h2>
          <pre className='text-sm bg-white p-2 rounded-md overflow-x-auto'>
            {JSON.stringify(results, null, 2)}
          </pre>
        </div>
      )}

      {wasmError && (
        <p className='text-red-500 text-sm text-center mt-4'>
          Error loading WASM: {wasmError}
        </p>
      )}
    </div>
  );
}

---

📋 Hasil Contoh Output (di Console)

{
  "email": {
    "input": "[e-mail]",
    "result": {
      "valid": true,
      "message": "Alamat email valid. Format dan domain sudah benar, bukan domain contoh atau domain sekali pakai, dan panjangnya tidak melebihi batas."
    },
    "error": null
  },
  "full name": {
    "input": "XYZ",
    "result": {
      "valid": false,
      "message": "Input 'XYZ' tidak terlihat seperti nama manusia, institusi, atau entitas yang realistis. Ini lebih menyerupai placeholder atau singkatan generik."
    },
    "error": null
  },
  "address": {
    "input": "My House",
    "result": {
      "valid": false,
      "message": "Input 'My House' terlalu umum dan tidak mengandung elemen geografis yang spesifik dan realistis seperti nama jalan, nomor, kota, atau kode pos. Ini tidak dapat digunakan sebagai alamat yang valid."
    },
    "error": null
  },
  "company name": {
    "input": "Companyy",
    "result": {
      "valid": false,
      "message": "Input 'Companyy' terlalu generik dan tidak terdengar seperti nama perusahaan yang spesifik atau realistis. Penulisan dengan dua 'y' di akhir juga terlihat tidak lazim untuk nama entitas asli, menyerupai placeholder atau nama uji coba. Mohon gunakan nama perusahaan yang lebih spesifik dan realistis."
    },
    "error": null
  }
}

---

💡 Catatan

• Fungsi validateInput() tetap digunakan seperti pada validasi tunggal.
• Perbedaan utamanya adalah semua input dikirim sekaligus menggunakan Promise.all() agar berjalan paralel.
• Kamu bisa menyesuaikan daftar input sesuai kebutuhan form atau dataset kamu.

---

---

📘 5️⃣ Ringkasan Fungsi Utama

Fungsi	Deskripsi
useWasm()	React Hook untuk memuat dan menginisialisasi modul WASM.
wasmModule.getSupportedModels()	Mengambil daftar model Gemini yang didukung.
validateInput(text, model, type)	Menjalankan validasi semantik pada teks yang diberikan.
wasmModule.configure(apiKey)	Wajib dipanggil sekali untuk menetapkan API Key Gemini sebelum fitur validasi dapat digunakan.

---

🐍 Python

Untuk Python, Anda dapat menginstal library ini langsung dari PyPI menggunakan pip.

pip install -i validation-semantic

Setelah terinstal, Anda bisa langsung mengimpor dan menggunakan fungsi validate_input_py di kode Python Anda:

from validation_semantic import validate_input_py, SupportedModel

---

🔑 Konfigurasi

Library ini memerlukan API Key dari Google AI Studio.

# Membuat .env dengan variabel berisi API key dari google studio anda :
GEMINI_API_KEY="API_KEY_ANDA"

---

🚀 Cara Penggunaan Untuk Python

import json
from validation_semantic import validate_input_py, SupportedModel

text_input = "PT Mencari Cinta Sejati"
input_type = "Nama Perusahaan"

model_choice = SupportedModel.GeminiFlash

result = validate_input_py(
    text=text_input,
    model=model_choice,
    label=input_type
)

print(json.dumps(result, indent=4, ensure_ascii=False))

Output:

{
  "valid": false,
  "message": "Input 'PT Mencari Cinta Sejati' adalah nama perusahaan yang tidak valid dan umum di Indonesia."
}

---

📦 Validasi Banyak Input Sekaligus (Batch Validation) dengan python

Kode Lengkap:

class BatchValidationWorker:
    def __init__(self, inputs, model):
        self.inputs = inputs
        self.model = model

    def run(self):
        results = {}
        for label, text in self.inputs.items():
            if not text.strip():
                continue  # lewati input kosong

            try:

                result = validate_input_py(text.strip(), self.model, label) #validate_input_py merupakan fungsi dari library
                results[label] = {
                    "input": text.strip(),
                    "result": result,
                    "error": None
                }
            except Exception as e:
                results[label] = {
                    "input": text.strip(),
                    "result": None,
                    "error": str(e)
                }
        return results

Contoh Penggunaan:

if __name__ == "__main__":
    user_inputs = {
        "nama": "John Doe",
        "email": "[e-mail]",
        "alamat": "error di sini"
    }
    model = SupportedModel.GeminiFlashLite
    worker = BatchValidationWorker(user_inputs, model)
    results = worker.run()

    print(results)
    json_output = json.dumps(results, indent=4, ensure_ascii=False)
    print("\n=== Hasil Validasi Batch ===")
    print(json_output)
    for label, info in results.items():
        print(f"[{label}]")
        print(" Input:", info["input"])
        if info["error"]:
            print(" ❌ Error:", info["error"])
        else:
            if info["result"]["valid"] == True:
                print(" ✅ Valid:", info["result"]["message"])
            else:
                print(" ⚠️  Invalid:", info["result"]["message"])

        print()

JSON Output:

{
  "email": {
    "input": "[e-mail]",
    "result": {
      "valid": true,
      "message": "Alamat email valid. Format dan domain sudah benar, bukan domain contoh atau domain sekali pakai, dan panjangnya tidak melebihi batas."
    },
    "error": null
  },
  "full name": {
    "input": "XYZ",
    "result": {
      "valid": false,
      "message": "Input 'XYZ' tidak terlihat seperti nama manusia, institusi, atau entitas yang realistis. Ini lebih menyerupai placeholder atau singkatan generik."
    },
    "error": null
  },
  "address": {
    "input": "My House",
    "result": {
      "valid": false,
      "message": "Input 'My House' terlalu umum dan tidak mengandung elemen geografis yang spesifik dan realistis seperti nama jalan, nomor, kota, atau kode pos. Ini tidak dapat digunakan sebagai alamat yang valid."
    },
    "error": null
  },
  "company name": {
    "input": "Companyy",
    "result": {
      "valid": false,
      "message": "Input 'Companyy' terlalu generik dan tidak terdengar seperti nama perusahaan yang spesifik atau realistis. Penulisan dengan dua 'y' di akhir juga terlihat tidak lazim untuk nama entitas asli, menyerupai placeholder atau nama uji coba. Mohon gunakan nama perusahaan yang lebih spesifik dan realistis."
    },
    "error": null
  }
}

🧩 Jenis Input yang Dapat Divalidasi

Library validation_semantic mendukung berbagai jenis input teks yang umum digunakan dalam aplikasi bisnis, akademik, maupun personal. Berikut daftar lengkap jenis input yang dapat divalidasi beserta fungsi atau konteks penggunaannya:

Kategori Validasi	Deskripsi	Label / Kata Kunci yang Didukung
📧 Email	Memvalidasi format email dan mengecek domain dummy (misal: example.com).	"email", "alamat email", "email address", "mail"
👤 Nama Orang	Memvalidasi apakah input terlihat seperti nama manusia asli.	"name", "nama", "full name", "nama lengkap", "nickname", "first name", "last name"
🆔 Username	Memvalidasi nama pengguna yang unik (tanpa spasi, konten pantas).	"username", "nama pengguna", "handle", "user id", "account name", "id pengguna"
🏢 Perusahaan	Memvalidasi nama entitas bisnis (PT, CV, Inc, Corp, dll).	"company", "perusahaan", "business", "corporate", "company name", "nama perusahaan"
🏛️ Institusi	Memvalidasi organisasi, lembaga, atau yayasan.	"institution", "institusi", "organization", "lembaga", "agency", "institute"
📦 Produk	Memvalidasi barang fisik, merchandise, atau item.	"product", "produk", "item", "barang", "merchandise", "goods", "nama barang"
💼 Pekerjaan	Memvalidasi judul pekerjaan, peran, atau status profesi.	"job", "pekerjaan", "profession", "profesi", "role", "career", "karir", "position"
📍 Lokasi	Memvalidasi venue, tempat umum, atau area.	"location", "lokasi", "place", "tempat", "venue", "area", "nama lokasi"
🏠 Alamat Fisik	Memvalidasi alamat jalan, termasuk konteks kota/kode pos.	"address", "alamat", "street address", "home address", "domicile"
🪪 Identitas (ID)	Memvalidasi NIK, KTP, Paspor, atau NPWP (Cek panjang & format).	"nik", "ktp", "npwp", "passport", "sim", "identity number", "nomor identitas"
📅 Tanggal & Waktu	Memvalidasi format tanggal, logika kalender, dan waktu realistis (Tgl Lahir).	"date", "tanggal", "dob", "birth date", "tgl lahir", "time", "waktu"
💰 Angka/Uang	Memvalidasi umur, harga, gaji, atau jumlah (Cek batasan nilai).	"age", "umur", "price", "harga", "salary", "gaji", "amount", "nominal", "cost"
🔗 URL/Website	Memvalidasi link web, domain, dan TLD (menolak localhost).	"website", "url", "link", "tautan", "domain", "homepage", "situs"
📝 Judul	Memvalidasi headline atau subjek untuk artikel/konten.	"title", "judul", "subject", "headline", "topic", "caption"
📄 Konten Teks	Memvalidasi teks isi, deskripsi, komentar, atau ulasan.	"content", "konten", "description", "deskripsi", "story", "comment", "review", "text area"
🏷️ Tag/Label	Memvalidasi kata kunci pendek atau kategori.	"tag", "kategori", "category", "label", "keyword", "tags"

💡 Catatan Penting: > Logika validasi library ini bersifat Semantik, bukan hanya sintaksis (format).

• Contoh 1: Memasukkan "12345" ke dalam kolom Nama akan ditolak, bukan hanya karena mengandung angka, tetapi karena "12345" tidak terlihat seperti nama manusia yang wajar.
• Contoh 2: Memasukkan "Jln. Sudirman No. 5" akan diterima sebagai Alamat, tetapi akan ditolak jika labelnya adalah Nama Orang.

---

🧠 Catatan:

• Semua jenis input di atas bersifat fleksibel — sistem akan mengenali label yang mirip (misalnya nama institusi dan lembaga akan diproses sama).
• Validasi tidak hanya berdasarkan format (regex), tetapi juga semantik dan konteks makna dengan bantuan model bahasa.

---

---

📊 Permintaan Partisipasi Dan Umpan Balik Riset

Pustaka Validasi Semantik dikembangkan sebagai bagian dari proyek riset akademis yang berfokus pada evaluasi performa dan kegunaan sistem validasi semantik berbasis AI.

Jika Anda seorang pengembang yang menggunakan pustaka ini, umpan balik Anda sangat berharga untuk riset ini. Silakan coba gunakan pustaka ini dengan berbagai jenis masukan seperti nama, alamat, judul, deskripsi, atau kolom teks, dan bagikan pengalaman Anda.

Anda dapat menyertakan:

• Pendapat Anda tentang kemudahan penggunaan dan pengalaman pengembang
• kinerja atau akurasi hasil validasi
• Masalah atau saran perbaikan yang ingin Anda laporkan
• (Opsional) Contoh atau bukti tentang bagaimana Anda mengintegrasikan pustaka ini ke dalam proyek Anda

Kontribusi Anda akan secara langsung mendukung evaluasi dan pengembangan lebih lanjut dari proyek riset ini.

📩 Anda dapat memberikan masukan dengan membuka Masalah di repositori GitHub resmi: 👉 GitHub Issues for PyPi users 👉 GitHub Issues for NPM users

Terima kasih banyak telah meluangkan waktu untuk berpartisipasi dan berkontribusi dalam penelitian ini. 🙏

---

---

🤝 Kontribusi

Kontribusi sangat diterima! Silakan buat issue atau pull request di GitHub Repository.

---

📄 Lisensi

Proyek ini dilisensikan di bawah MIT License.

---

Changelog

1.1.3 - 2025-11-22

• Pemindahan konfigurasi API Key keluar dari validateInput() → sekarang wajib memanggil wasmModule.configure(apiKey) sekali setelah Wasm module siap pada React.
• Refactor: Meningkatkan kenyamanan penggunaan API Python serta konsistensi penamaan.
• Memperbarui daftar model yang didukung untuk memasukkan model Gemini terbaru.
• Meningkatkan dokumentasi dan contoh penggunaan pada README.