Metadata-Version: 2.4
Name: sasaknlp
Version: 0.2.2
Summary: An open-source NLP and morphological processing toolkit for the low-resource Sasak language.
Author: kodetr
License: MIT
Project-URL: Homepage, https://kodetr.com
Project-URL: Repository, https://github.com/kodetr/sasaknlp
Project-URL: Documentation, https://github.com/kodetr/sasaknlp#readme
Project-URL: Demo Web, https://huggingface.co/spaces/kodetr/sasaknlp-demo
Project-URL: Dataset, https://huggingface.co/datasets/kodetr/sasak-benchmark-100k
Keywords: nlp,sasak,morphology,stemmer,low-resource-language,computational-linguistics,indonesian-languages
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# SasakNLP: Research-Grade Low-Resource Language NLP Toolkit

[![PyPI version](https://img.shields.io/pypi/v/sasaknlp.svg?color=4F46E5)](https://pypi.org/project/sasaknlp/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/sasaknlp.svg?color=blue)](https://pypi.org/project/sasaknlp/)
[![Tests: 120 passed](https://img.shields.io/badge/tests-120%20passed-brightgreen.svg)]()
[![Corpora: 17.8k Verified](https://img.shields.io/badge/corpora-17.8k%20authentic-orange.svg)]()
[![Dialects: 5 Supported](https://img.shields.io/badge/dialects-5%20Sasak%20clusters-purple.svg)]()
[![Script: Aksara Sasak Unicode](https://img.shields.io/badge/script-Aksara%20Sasak%20(Balinese%20Unicode)-success.svg)]()
[![POS Tagging: UD v2](https://img.shields.io/badge/POS%20Tagging-Universal%20Dependencies%20v2-teal.svg)]()
[![Cross-Dialect: 5 Clusters](https://img.shields.io/badge/cross--dialect-5%20clusters%20converter-blueviolet.svg)]()
[![Translation: Sasak ↔ Indonesia](https://img.shields.io/badge/translation-Sasak%20%E2%86%94%20Indonesia-red.svg)]()
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

**SasakNLP** adalah toolkit Pemrosesan Bahasa Alami (*Natural Language Processing* / NLP) dan komputasi morfologi berbasis riset untuk **Bahasa Sasak** (*Basa Sasak*), bahasa daerah berumpun Austronesia yang dituturkan oleh sekitar 3 juta jiwa di Pulau Lombok, Nusa Tenggara Barat (NTB), Indonesia.

SasakNLP dibangun dengan **Arsitektur Hibrida Berbasis Aturan & Validasi Leksikon Otoritatif (*Dictionary-Enhanced Rule-Based Architecture*)**, dilengkapi:
- ✂️ **Multi-Tier 3-Pass Morphological Stemmer**: Lemmatisasi afiksasi bertingkat, konfiks, sisipan, reduplikasi, dan klitika posesif (`-ne`, `-ku`, `-de`).
- 🏷️ **Contextual POS Tagger (UD v2)**: Tagging kelas kata (*Part-of-Speech*) kontekstual mengadopsi standar internasional Universal Dependencies (`NOUN`, `VERB`, `ADJ`, `PRON`, dll.) melalui inferensi hibrida leksikon, afiksasi, dan aturan urutan sintaksis.
- 🔄 **Cross-Dialect Converter (5 Dialek Mahsun)**: Mesin translasi dan konverter kalimat antar-5 dialek utama Sasak (*Meno-Mene, Ngeno-Ngene, Mriak-Mriku, Kuto-Kute, Ngeto-Ngete*) berbasis 35 isoglos komparatif Prof. Dr. Mahsun.
- 🗺️ **Deteksi 5 Dialek Sasak**: Klasifikasi otomatis untuk dialek *Meno-Mene (Selaparang)*, *Ngeno-Ngene*, *Meriak-Meriku*, *Kuto-Kute*, dan *Ngeto-Ngete*.
- 🔤 **Transliterasi Aksara Sasak / Jejawan (Hanacaraka Unicode Balinese)**: Konversi dua arah Latin $\leftrightarrow$ Aksara Sasak, deteksi aksara, dukungan serapan konsonan Indonesia (`f, v, z, sy`), serta deteksi dialek langsung dari teks Aksara Sasak.
- 🇮🇩 **Penerjemahan Dwibahasa (Sasak $\leftrightarrow$ Indonesia)**: Terhubung langsung dengan leksikon resmi Balai Bahasa Provinsi NTB.
- 📚 **17.813 Entri Korpus Autentik Terverifikasi**: Terdiri dari kamus leksikal, kalimat alami, cerita rakyat paralel 24 bab, percakapan tematik sehari-hari, peribahasa *sesenggakan*, dan pantun tradisional *lelakaq*.

---

## 📦 Panduan Instalasi (Installation)

### Melalui PyPI (Direkomendasikan)

Pasang paket resmi langsung menggunakan `pip`:

```bash
pip install sasaknlp
```

Verifikasi instalasi:
```bash
python3 -c "import sasaknlp; print('SasakNLP version:', sasaknlp.__version__)"
```

### Dari Sumber GitHub (Pengembangan & Riset)

```bash
git clone https://github.com/kodetr/sasaknlp.git
cd sasaknlp
pip install -e ".[dev]"
```

---

## 🚀 Cara Penggunaan (Quickstart & Usage Guide)

### 1. Analisis Kalimat Lengkap / End-to-End Pipeline (`SasakNLP`)

Kelas `SasakNLP` menjalankan pipeline komprehensif: normalisasi teks, tokenisasi, deteksi dialek, lemmatisasi, dekonstruksi aturan morfologi, dan kalkulasi latensi komputasi.

```python
from sasaknlp import SasakNLP

# Inisialisasi pipeline
nlp = SasakNLP()

# Analisis kalimat autentik bahasa Sasak
result = nlp.process("Tiyang mangan nasiq menu meni kance baturne.")

print("Teks Ternormalisasi :", result.normalized_text)
print("Dialek Terdeteksi   :", result.dialect)
print("Daftar Token Kata   :", result.tokens)
print("Kata Dasar (Lemmas) :", result.lemmas)
print("Latensi Eksekusi    :", f"{result.latency_ms:.2f} ms")

# Rincian analisis morfologi per kata
print("\nDekonstruksi Morfologi Tiap Token:")
for a in result.analyses:
    print(f" • {a.surface_form:14} -> {a.lemma:10} | Aturan: {a.rule_applied:24} | Keyakinan: {a.confidence:.2%}")
```

**Output:**
```text
Teks Ternormalisasi : tiyang mangan nasiq menu meni kance baturne.
Dialek Terdeteksi   : selaparang
Daftar Token Kata   : ['tiyang', 'mangan', 'nasiq', 'menu', 'meni', 'kance', 'baturne']
Kata Dasar (Lemmas) : ['tiyang', 'mangan', 'nasiq', 'menu', 'meni', 'kance', 'batur']
Latensi Eksekusi    : 0.11 ms

Dekonstruksi Morfologi Tiap Token:
 • tiyang         -> tiyang     | Aturan: direct_lexicon_lookup    | Keyakinan: 100.00%
 • mangan         -> mangan     | Aturan: direct_lexicon_lookup    | Keyakinan: 100.00%
 • nasiq          -> nasiq      | Aturan: direct_lexicon_lookup    | Keyakinan: 100.00%
 • menu           -> menu       | Aturan: direct_lexicon_lookup    | Keyakinan: 100.00%
 • meni           -> meni       | Aturan: direct_lexicon_lookup    | Keyakinan: 100.00%
 • kance          -> kance      | Aturan: direct_lexicon_lookup    | Keyakinan: 100.00%
 • baturne        -> batur      | Aturan: possessive_ne            | Keyakinan: 97.73%
```

---

### 2. Penerjemahan Dwibahasa (Sasak $\leftrightarrow$ Indonesia)

SasakNLP menyediakan fungsi penerjemahan leksikal dua arah yang terintegrasi dengan leksikon Balai Bahasa Provinsi NTB:

```python
from sasaknlp import sasak_to_indonesia, indonesia_to_sasak

# Terjemah Sasak -> Bahasa Indonesia
print(sasak_to_indonesia("mangan"))  # 'makan'
print(sasak_to_indonesia("tiyang"))  # 'saya (ragam halus)'
print(sasak_to_indonesia("bale"))    # 'rumah'
print(sasak_to_indonesia("solah"))   # 'bagus; baik; elok'

# Terjemah Bahasa Indonesia -> Ragam Kosakata Sasak (termasuk dialek)
hasil_sasak = indonesia_to_sasak("makan")
for entri in hasil_sasak:
    print(f"Sasak: {entri['sasak']:10} | Dialek: {entri['dialect']:12} | Arti: {entri['meaning_id']}")
```

**Output:**
```text
Sasak: kaken      | Dialek: selaparang   | Arti: makan (ragam halus)
Sasak: mangan     | Dialek: general      | Arti: makan
Sasak: amah       | Dialek: general      | Arti: makan (ragam kasar)
```

---

### 3. Transliterasi Aksara Sasak / Jejawan (Hanacaraka Unicode Balinese)

Bahasa Sasak secara historis ditulis menggunakan aksara abugida turunan Kawi/Jawa (*Aksara Sasak / Hanacaraka / Jejawan*), yang dalam konsorsium Unicode distandarisasi di bawah blok **Balinese Unicode (U+1B00 - U+1B7F)**.

SasakNLP mendukung transliterasi fonemis dua arah, tanda baca tradisional (*carik siki* `᭞`, *carik kalih* `᭟`), angka aksara, konsonan serapan Indonesia (`f, v, z, sy`), serta deteksi dialek dari aksara:

```python
from sasaknlp import latin_to_aksara, aksara_to_latin, is_aksara, detect_dialect_aksara

# 1. Konversi Teks Latin ke Aksara Sasak Unicode
aksara = latin_to_aksara("sasak")
print(aksara)  # 'ᬲᬲᬓ᭄'

# 2. Kalimat lengkap dengan angka dan tanda baca
kalimat_aksara = latin_to_aksara("Tiyang batur sasak 2026, solah.")
print(kalimat_aksara)  # 'ᬢᬶᬬᬂ ᬩᬢᬸᬃ ᬲᬲᬓ᭄ ᭒᭐᭒᭖᭞ ᬲᭀᬮᬄ᭟'

# 3. Transliterasi balik dari Aksara Sasak ke Latin
print(aksara_to_latin(kalimat_aksara))  # 'tiyang batur sasak 2026, solah.'

# 4. Pengecekan skrip aksara (Script detection)
print(is_aksara("ᬲᬲᬓ᭄"))  # True
print(is_aksara("sasak"))    # False

# 5. Deteksi Dialek langsung dari Teks Aksara Sasak
dialek, conf = detect_dialect_aksara("ᬢᬶᬬᬂ ᬫᬗᬦ᭄ ᬦᬲᬶᬓ᭄ ᬫᭂᬦᬸ ᬫᭂᬦᬶ")
print(f"Dialek Aksara: {dialek} (Keyakinan: {conf:.0%})")
# Output: Dialek Aksara: selaparang (Keyakinan: 95%)
```

---

### 4. Deteksi 5 Dialek Bahasa Sasak (`DialectDetector`)

Mendeteksi 5 dialek kanonik berdasarkan penanda leksikal diagnostik (*shibboleths*) dari penelitian **Prof. Dr. Mahsun (UNRAM)** dan **Balai Bahasa NTB**. Menerima input berupa teks kalimat Latin, daftar token, maupun Aksara Sasak:

```python
from sasaknlp import DialectDetector

detector = DialectDetector()

# A. Deteksi dari kalimat Latin (Dialek Ngeno-Ngene)
dialek1, conf1 = detector.detect_text("Aku ngeno ngene kance ente leq Mataram.")
print(f"Dialek: {dialek1} ({conf1:.0%})")
# Output: Dialek: ngeno_ngene (95%)

# B. Deteksi dari kalimat Latin (Dialek Meriak-Meriku)
dialek2, conf2 = detector.detect_text("Mriak mriku ite pade lalo beraye leq Praya.")
print(f"Dialek: {dialek2} ({conf2:.0%})")
# Output: Dialek: mriak_mriku (95%)

# C. Deteksi langsung dari teks Aksara Sasak
dialek3, conf3 = detector.detect_text("ᬢᬶᬬᬂ ᬫᬗᬦ᭄ ᬦᬲᬶᬓ᭄ ᬫᭂᬦᬸ ᬫᭂᬦᬶ")
print(f"Dialek: {dialek3} ({conf3:.0%})")
# Output: Dialek: selaparang (95%)
```

---

### 5. Part-of-Speech Tagging Kontekstual (`SasakPOSTagger` & `pos_tag`)

SasakNLP menyediakan model POS tagging sekuensial yang mengadopsi standar internasional **Universal Dependencies (UD v2)** (`NOUN`, `VERB`, `ADJ`, `ADV`, `PRON`, `ADP`, `CCONJ`, `SCONJ`, `DET`, `NUM`, `PART`, `PROPN`, `AUX`, `INTJ`, `PUNCT`). Model ini menggabungkan pencocokan leksikon kamus, inferensi afiks morfologi Sasak, dan aturan resolusi sintaksis:

```python
from sasaknlp import pos_tag, SasakPOSTagger

# A. Penggunaan praktis tingkat fungsi
kalimat = "Tiyang mangan nasiq leq bale"
tags = pos_tag(kalimat)
print(tags)
# Output: [('Tiyang', 'PRON'), ('mangan', 'VERB'), ('nasiq', 'NOUN'), ('leq', 'ADP'), ('bale', 'NOUN')]

# B. Disambiguasi sintaktis dan gelar kehormatan Sasak (Lalu, Baiq, Raden)
print(pos_tag("Lalu Gde lalo ojok Mataram kance batur"))
# Output: [('Lalu', 'PROPN'), ('Gde', 'PROPN'), ('lalo', 'VERB'), ('ojok', 'ADP'), ('Mataram', 'PROPN'), ('kance', 'ADP'), ('batur', 'NOUN')]

# C. Anotasi mendalam beserta aturan inferensi & skor keyakinan
tagger = SasakPOSTagger()
for dt in tagger.tag_detailed("Bale niki solah gati"):
    print(f" • {dt.word:10} -> {dt.tag:6} | Aturan: {dt.rule:25} | Keyakinan: {dt.confidence:.2f}")
```

---

### 6. Konversi dan Translasi Lintas Dialek (`SasakDialectConverter` & `convert_dialect`)

SasakNLP menyediakan mesin penerjemah lintas dialek (*Cross-Dialect Converter*) untuk **5 dialek utama** bahasa Sasak (*Meno-Mene, Ngeno-Ngene, Mriak-Mriku, Kuto-Kute, Ngeto-Ngete*) yang didasarkan pada 35 isoglos komparatif Prof. Dr. Mahsun (1989, 2006). Mendukung substitusi frasa majemuk, pelestarian klitika/afiks, dan penyesuaian kapitalisasi:

```python
from sasaknlp import convert_dialect, SasakDialectConverter

# A. Konversi langsung antar-dialek
# Ngeno-Ngene -> Meno-Mene (Selaparang)
teks_meno = convert_dialect("Ngeno ngene kance ente", target="meno_mene", source="ngeno_ngene")
print("Meno-Mene  :", teks_meno)
# Output: Menu meni kance side

# Ngeno-Ngene -> Kuto-Kute (Lombok Utara)
teks_kuto = convert_dialect("Ngeno ngene kance ente", target="kuto_kute", source="ngeno_ngene")
print("Kuto-Kute  :", teks_kuto)
# Output: Kuto kute kance kamu

# Ngeno-Ngene -> Mriak-Mriku (Lombok Tengah)
teks_mriak = convert_dialect("Ngeno ngene kance ente", target="mriak_mriku", source="ngeno_ngene")
print("Mriak-Mriku:", teks_mriak)
# Output: Mriak mriku kance kamu

# B. Deteksi dialek asal secara otomatis (source='auto')
print(convert_dialect("Ngeno ngene leq Mataram", target="meno_mene"))
# Output: 'Menu meni leq Mataram'

# C. Pelestarian enklitika kepemilikan (-ne, -ku, -de)
converter = SasakDialectConverter()
hasil = converter.convert("gedengne", target_dialect="ngeno_ngene", source_dialect="kuto_kute")
print("Hasil konversi:", hasil.converted_text)  # 'balene' (gedeng -> bale + -ne)
```

---

### 7. Stemmer & Morfologi Sasak Berjenjang (`SasakStemmer` & `SasakStem`)

Bahasa Sasak memiliki struktur morfologi aglutinatif yang kaya dengan variasi afiks dan klitika:

```python
from sasaknlp import SasakStemmer, SasakStem

stemmer = SasakStemmer()

# Awalan (Prefix)
print(stemmer.stem("tepinaq"))          # 'pinaq'   (awalan te-)
print(stemmer.stem("pemangan"))         # 'mangan'  (awalan pe-)

# Akhiran (Suffix)
print(stemmer.stem("tulungang"))        # 'tulung'  (akhiran -ang)
print(stemmer.stem("kaduan"))           # 'kadu'    (akhiran -an)

# Sisipan (Infix)
print(stemmer.stem("tinulung"))         # 'tulung'  (sisipan -in-)

# Konfiks (Circumfix)
print(stemmer.stem("kasolahan"))        # 'solah'   (konfiks ka-...-an)
print(stemmer.stem("pembelangan"))      # 'bela'    (konfiks pe-...-an + nasal)

# Kata Ulang (Reduplication)
print(stemmer.stem("bareng-bareng"))    # 'bareng'  (reduplikasi murni)

# Klitika Kepemilikan (Possessive Clitics)
print(stemmer.stem("baturne"))          # 'batur'   (klitika -ne: temannya)
print(stemmer.stem("balengku"))         # 'bale'    (klitika -ku: rumahku)
print(stemmer.stem("bukunde"))          # 'buku'    (klitika -de: bukumu)

# Multi-Tier 3-Pass Stemmer (Afiksasi Bertumpuk & Kompleks)
stem3 = SasakStem()
print(stem3.stem("kalandarande"))       # 'landar'  (ka- + landar + -an + -de)
print(stem3.stem("pebadarande"))        # 'badar'   (pe- + badar + -an + -de)
print(stem3.stem("iteminne"))           # 'item'    (item + -in + -ne)
print(stem3.stem("beperadok-peradok"))  # 'peradok' (be- + peradok-peradok)
```

---

### 8. Penyaringan Kata Henti / Stopwords (`remove_stopwords`)

SasakNLP menyertakan korpus stopwords terverifikasi sebanyak 159 kata tugas (konjungsi, partikel, preposisi) khas bahasa Sasak:

```python
from sasaknlp import remove_stopwords, is_stopword, get_stopwords

# Cek kata henti
print(is_stopword("dait"))    # True (kata hubung 'dan')
print(is_stopword("leq"))     # True (preposisi 'di')
print(is_stopword("mangan"))  # False (verba 'makan')

# Hapus stopwords dari kalimat
kalimat = "Tiyang mangan nasiq leq bale dait nginem kupi."
bersih = remove_stopwords(kalimat)
print(bersih)
# Output: 'mangan nasiq bale nginem kupi.'
```

---

### 9. Akses Kamus Otoritatif Balai Bahasa NTB (`SasakLexManager`)

```python
from sasaknlp import SasakLexManager

lex = SasakLexManager()

# Pencarian entri lema
entri = lex.lookup("mangan")
if entri:
    print("Kata Dasar :", entri.lemma)
    print("Kelas Kata :", entri.pos)
    print("Definisi   :", entri.meaning_id)
    print("Dialek     :", entri.dialect)
    print("Sumber     :", entri.source)

# Pencarian awalan kata (Prefix Search menggunakan PrefixTrie)
kata_berawalan_ba = lex.search_prefix("ba")
print(f"Jumlah kata berawalan 'ba-': {len(kata_berawalan_ba)}")
```

---

### 10. Memuat Dataset Autentik Terverifikasi (`datasets/`)

SasakNLP menyediakan dataset terverifikasi dalam format `.json`, `.jsonl`, dan `.csv` yang dapat dimuat langsung untuk riset *machine learning* dan komputasi linguistik:

```python
import json

# 1. Cerita Rakyat Paralel Dwibahasa Sasak - Indonesia (24 Bab Legenda)
with open("datasets/parallel/sasak_indonesia_parallel.jsonl", "r", encoding="utf-8") as f:
    cerita_pertama = json.loads(f.readline())
    print("Judul Bab  :", cerita_pertama["story_title"])
    print("Sasak      :", cerita_pertama["sasak"])
    print("Indonesia  :", cerita_pertama["indonesia"])

# 2. Percakapan Kontekstual Sehari-hari Dwibahasa (40 Dialog)
with open("datasets/parallel/sasak_indonesia_conversations.jsonl", "r", encoding="utf-8") as f:
    dialog_pertama = json.loads(f.readline())
    print("Topik      :", dialog_pertama["topic"])
    print("Sasak      :", dialog_pertama["sasak"])
    print("Indonesia  :", dialog_pertama["indonesia"])

# 3. Sesenggakan (40 Peribahasa Tradisional Sasak & Makna Filosofis)
with open("datasets/corpus/sesenggakan_sasak.json", "r", encoding="utf-8") as f:
    sesenggakan = json.load(f)
    print("Peribahasa :", sesenggakan[0]["peribahasa"])
    print("Arti       :", sesenggakan[0]["arti_harfiah_id"])
    print("Filosofi   :", sesenggakan[0]["makna_filosofis_id"])

# 4. Lelakaq (10 Bait Pantun Tradisional Sasak & Nilai Moral)
with open("datasets/corpus/lelakaq_sasak.json", "r", encoding="utf-8") as f:
    lelakaq = json.load(f)
    print("Pantun     :\n" + lelakaq[0]["bait_sasak"])
    print("Terjemahan :\n" + lelakaq[0]["terjemahan_id"])
```

---

### 11. Perintah Antarmuka Baris Perintah (CLI)

Setelah memasang via `pip install sasaknlp`, perintah `sasaknlp` langsung aktif di terminal:

```bash
# 1. Stemming kata tunggal
sasaknlp stem "tepinaq"

# 2. Analisis morfologi mendalam
sasaknlp analyze "kelororan"

# 3. Proses kalimat penuh (dengan POS tags & dialek)
sasaknlp process "Tiyang mangan nasiq menu meni kance baturne."

# 4. Part-of-Speech Tagging (Universal Dependencies UD v2)
sasaknlp tag "Tiyang mangan nasiq leq bale"
sasaknlp tag "Bale niki solah gati" --json

# 5. Konversi Lintas Dialek (5 Dialek Mahsun 1989, 2006)
sasaknlp convert-dialect "Ngeno ngene kance ente" --target meno_mene
sasaknlp convert-dialect "Ngeno ngene kance ente" --target kuto_kute --json

# 6. Pencarian lema di kamus resmi Balai Bahasa NTB
sasaknlp lexicon lookup "mangan"
sasaknlp lexicon search "ba"

# 7. Evaluasi akurasi benchmark
sasaknlp evaluate --benchmark datasets/benchmark/synthetic_benchmark.csv
```

---

## 🔬 Arsitektur Riset & Metodologi Ilmiah

SasakNLP mengatasi masalah umum NLP bahasa daerah (*understemming*, *overstemming*, dan kerancuan dialek) melalui pipeline sistematis 6-tahap:

```text
               ┌───────────────────────────────┐
               │          INPUT TEXT           │
               └──────────────┬────────────────┘
                              │
                              ▼
               ┌───────────────────────────────┐
               │      TEXT NORMALIZATION       │
               │   (NFC, Glottals, Quotes)     │
               └──────────────┬────────────────┘
                              │
                              ▼
               ┌───────────────────────────────┐
               │         TOKENIZATION          │
               │  (Reduplications, Enclitics)  │
               └──────────────┬────────────────┘
                              │
                              ▼
               ┌───────────────────────────────┐
               │    DIALECT CONTEXTUALIZATION  │
               │ (Markers: Selaparang, Ngeno)  │
               └──────────────┬────────────────┘
                              │
               ┌──────────────┴───────────────┐
               ▼                              ▼
      [Direct Lexicon Lookup]        [Rule Morphological Engine]
       (Is word already root?)                    │
               │                                  ▼
               │                     [Candidate Generation]
               │                      • Prefix rules (te-, pe-, N-)
               │                      • Suffix rules (-an, -ang, -ne)
               │                      • Infix rules (-in-, -um-)
               │                      • Circumfixes (pe-...-an, te-...-ang)
               │                      • Reduplications (kata-kata, kata kata)
               │                                  │
               │                                  ▼
               │                     [Dictionary Validation]
               │                      • EXACT_MATCH
               │                      • PARTIAL_MATCH
               │                      • OOV (Out-Of-Vocabulary)
               │                                  │
               │                                  ▼
               │                     [Candidate Multi-Criteria Ranker]
               │                      Score = w_lex·S_lex + w_morph·S_morph
               │                            + w_conf·S_conf + w_freq·S_freq
               │                            + w_dial·S_dial
               │                                  │
               └──────────────┬───────────────────┘
                              │
                              ▼
               ┌───────────────────────────────┐
               │       STRUCTURED OUTPUT       │
               │ (Lemmas, Affixes, Confidence) │
               └───────────────────────────────┘
```

<p align="center">
  <img src="https://huggingface.co/datasets/kodetr/sasak-benchmark-100k/resolve/main/figures/fig5_dataset_acquisition_pipeline.png" alt="Figure 5: Dataset Acquisition & Curation Protocol" width="100%">
  <br>
  <em><b>Gambar 5:</b> Protokol ilmiah akuisisi data multi-sumber, kurasi leksikografis 5-tahap, dan verifikasi 17.813 entri data autentik referensi SasakNLP.</em>
</p>

---

## 🗺️ Klasifikasi 5 Dialek Utama Bahasa Sasak

Berdasarkan taksonomi dialektologi standar (**A. Teeuw 1958**, **Prof. Dr. Mahsun 2006**, dan **Balai Bahasa Provinsi NTB**):

| No | Gugus Dialek | Sebaran Wilayah | Penanda Diagnostik (*Shibboleths*) | Ciri Khas Linguistik |
| :---: | :--- | :--- | :--- | :--- |
| **1** | **Selaparang (Meno-Mene)** | Lombok Timur & Lombok Tengah Bagian Timur | `menu`, `meni`, `meno`, `mene`, `tiyang`, `kaken` | Ragam halus (*kramak/alus*), retensi glotal |
| **2** | **Ngeno-Ngene** | Kota Mataram, Lombok Barat, Lombok Tengah Barat | `ngeno`, `ngene`, `ente`, `aku` | Dialek perkotaan dan pesisir barat |
| **3** | **Meriak-Meriku** | Lombok Tengah Bagian Selatan (Praya, Pujut) | `mriak`, `mriku`, `meriq`, `merik` | Deiksis spasial terarah yang khas |
| **4** | **Ngeto-Ngete** | Lombok Timur Laut (Suela, Sembalun) | `ngeto`, `ngete` | Variasi dataran tinggi lereng Gunung Rinjani |
| **5** | **Kuto-Kute** | Lombok Utara (Bayan, Tanjung) | `kuto`, `kute`, `wetu` | Klaster arkais dengan fitur awal Austronesia |
| **6** | **Sasak Umum** | Seluruh Pulau Lombok | `wah`, `ndeq`, `mangan`, `batur` | Ragam komunikasi umum lintas pulau |

<p align="center">
  <img src="https://huggingface.co/datasets/kodetr/sasak-benchmark-100k/resolve/main/figures/fig2_dialect_performance.png" alt="Figure 2: Performance Evaluation across the 5 Sasak Dialects" width="100%">
  <br>
  <em><b>Gambar 2:</b> Evaluasi empiris akurasi dan F1-score pada 5 gugus dialek Sasak (Selaparang, Ngeno-Ngene, Meriak-Meriku, Ngeto-Ngete, dan Kuto-Kute). Memperlihatkan generalisasi lintas-dialek yang stabil di atas 85%.</em>
</p>

---

## 📊 Hasil Evaluasi & Tolok Ukur Ilmiah (Benchmark)

Dievaluasi terhadap dataset emas terkurasi dan kamus resmi **Balai Bahasa Provinsi NTB**:

| Metrik Evaluasi | Nilai Terukur | Makna Akademik |
| :--- | :---: | :--- |
| **Morphological Accuracy** | **87.98%** | Akurasi identifikasi kata dasar & afiksasi |
| **Macro Precision** | **99.00%** | Presisi luar biasa dalam validasi morfologi |
| **Macro Recall** | **95.35%** | Cakupan luas afiks infleksional & derivaksional |
| **Macro F1-Score** | **96.22%** | Keseimbangan harmonis antara presisi dan recall |
| **Weighted F1-Score** | **91.55%** | Ketangguhan pada frekuensi kata tinggi maupun rendah |
| **Kecepatan Mesin (Throughput)** | **22.500 kata/detik** | Bebas dependensi ML berat, eksekusi sub-milidetik |
| **Latensi Rata-rata** | **0.044 ms/kata** | Siap integrasi waktu-nyata (*real-time production*) |

<p align="center">
  <img src="https://huggingface.co/datasets/kodetr/sasak-benchmark-100k/resolve/main/figures/fig1_morphology_accuracy.png" alt="Figure 1: Morphological Disambiguation Accuracy by Affix Class" width="100%">
  <br>
  <em><b>Gambar 1:</b> Disagregasi akurasi morfologi berdasarkan kelas afiks (awalan, akhiran, sisipan, konfiks, dan reduplikasi) pada dataset tolok ukur terverifikasi.</em>
</p>

### Distribusi Taksonomi Galat (Error Taxonomy):
- **Prediksi Benar (Correct Prediction)**: **87.98%**
- **Di Luar Kosakata (Out-Of-Vocabulary / OOV)**: **11.92%** (Ditangani aman tanpa kesalahan pemotongan)
- **Pemotongan Kurang (Understemming)**: **0.09%**
- **Lemma Keliru (Incorrect Lemma)**: **0.01%**
- **Pemotongan Berlebih (Overstemming)**: **0.00%** (Nol galat pemotongan akar kata)

<p align="center">
  <img src="https://huggingface.co/datasets/kodetr/sasak-benchmark-100k/resolve/main/figures/fig3_error_taxonomy.png" alt="Figure 3: Error Taxonomy and Failure Mode Analysis" width="100%">
  <br>
  <em><b>Gambar 3:</b> Distribusi taksonomi galat (kiri: diagram donat) dan matriks diagnostik mode kegagalan (kanan). Sistem mengeliminasi overstemming (0.00%) dan understemming (0.09%) melalui gerbang leksikon ganda.</em>
</p>

### ⚡ Skalabilitas Komputasi & Efisiensi Waktu

SasakNLP dioptimalkan untuk eksekusi server maupun edge tanpa dependensi framework besar:

<p align="center">
  <img src="https://huggingface.co/datasets/kodetr/sasak-benchmark-100k/resolve/main/figures/fig4_pipeline_benchmark.png" alt="Figure 4: Computational Throughput and Latency Benchmarks" width="100%">
  <br>
  <em><b>Gambar 4:</b> Skalabilitas komputasi dan performa runtime. Menghasilkan throughput tinggi (22.500 kata/detik) dengan kurva latensi datar pada berbagai panjang teks.</em>
</p>

---

## 📚 Ringkasan Dataset Terverifikasi (17.813 Entri Autentik)

Semua dataset tersedia dalam repositori pada direktori [`datasets/`](datasets/):

| Kategori | Berkas Dataset | Jumlah Data | Sumber Otoritatif |
| :--- | :--- | :---: | :--- |
| **Korpus Kalimat Alami** | [`datasets/corpus/sasak_sentences_large.jsonl`](datasets/corpus/sasak_sentences_large.jsonl) | **12.591** kalimat | Korpus teks alami dari tim penerjemah Sasak & LAI |
| **Kamus Balai Bahasa NTB** | [`datasets/sasaklex/kamus_balai_bahasa_ntb.json`](datasets/sasaklex/kamus_balai_bahasa_ntb.json) | **2.761** lema | Balai Bahasa NTB (Lema, Kelas Kata, Dialek, Definisi ID) |
| **Leksikon Dasar SasakNLP** | [`datasets/sasaklex/default_lexicon.json`](datasets/sasaklex/default_lexicon.json) | **1.990** lema | Kosakata terverifikasi Sasak $\leftrightarrow$ Indonesia |
| **Austronesian Vocabulary (ABVD)** | [`datasets/sasaklex/abvd_sasak_vocabulary.json`](datasets/sasaklex/abvd_sasak_vocabulary.json) | **210** lema | Austronesian Basic Vocabulary Database (Max Planck / Dr. Peter K. Austin) |
| **Korpus Paralel (Cerita Rakyat)** | [`datasets/parallel/sasak_indonesia_parallel.jsonl`](datasets/parallel/sasak_indonesia_parallel.jsonl) | **136** pasang | 24 bab legenda Sasak (*Dewi Rengganis, Datu Penyampak, Batu Goloq, dll.*) |
| **Percakapan Sehari-hari** | [`datasets/parallel/sasak_indonesia_conversations.jsonl`](datasets/parallel/sasak_indonesia_conversations.jsonl) | **40** dialog | Dialog tematik kontekstual (*pasar, bertani, menenun, upacara begawe*) |
| **Sesenggakan (Peribahasa)** | [`datasets/corpus/sesenggakan_sasak.json`](datasets/corpus/sesenggakan_sasak.json) | **40** butir | Peribahasa tradisional Sasak + arti harfiah & makna filosofis ID |
| **Lelakaq (Pantun Tradisional)** | [`datasets/corpus/lelakaq_sasak.json`](datasets/corpus/lelakaq_sasak.json) | **10** bait | Pantun 4 baris berima a-b-a-b + terjemahan puitis & nilai moral ID |
| **Diagnostik 5 Dialek** | [`datasets/dialect/dialect_comparative_mahsun.json`](datasets/dialect/dialect_comparative_mahsun.json) | **35** lema komparatif | Pemetaan 5 dialek Sasak karya Prof. Dr. Mahsun |
| **TOTAL DATA UNIK** | | **17.813** | **100% Autentik & Bebas Data Sintetis** |

> 📖 **Dokumentasi Lengkap Provenansi & Sumber Data**: Uraian rinci institusi penerbit, pakar linguistik lapangan, monograf rujukan, dan protokol kurasi dapat dibaca pada [**`docs/sumber_dan_provenansi_dataset.md`**](docs/sumber_dan_provenansi_dataset.md).

---

## 🗂 Struktur Repositori

```text
sasaknlp/
├── pyproject.toml              # Konfigurasi paket (PEP 517/518) & metadata PyPI
├── requirements.txt            # Zero external runtime dependencies
├── requirements-dev.txt        # Dependensi pengujian (pytest, mypy, flake8)
├── LICENSE                     # Lisensi MIT Open Source
├── README.md                   # Dokumentasi lengkap & panduan penggunaan
│
├── src/sasaknlp/
│   ├── core/                   # Pipeline orchestrator, config, and data types
│   ├── tokenizer/              # Tokenizer kata & kalimat dengan retensi kata ulang
│   ├── normalization/          # Unicode NFC, normalisasi glotal apostrof, dan casefold
│   ├── lexicon/                # SasakLex manager, loader, PrefixTrie, penerjemahan ID
│   ├── morphology/             # Mesin aturan morfologi, candidate generator, analyzer
│   │   └── rules/              # Aturan awalan, akhiran, sisipan, konfiks, reduplikasi
│   ├── stemmer/                # Validator kamus, multi-criteria ranker, SasakStemmer
│   ├── stopwords/              # Stopwords bahasa Sasak (159 kata tugas) & filter
│   ├── dialect/                # Detektor dialek (5 dialek Sasak dari teks & aksara)
│   ├── transliteration/        # Transliterasi dua arah Latin ↔ Aksara Sasak Unicode
│   ├── evaluation/             # Evaluator akurasi, metrik ilmiah, dan taksonomi galat
│   └── cli/                    # CLI commands: stem, analyze, process, lexicon, evaluate
│
├── datasets/
│   ├── sasaklex/               # Kamus Balai Bahasa NTB (2.761 lema) & kosakata ABVD (210)
│   ├── corpus/                 # Korpus kalimat alami (12.591), Sesenggakan (40), Lelakaq (10)
│   ├── parallel/               # Cerita rakyat paralel Sasak-Indonesia (136) & percakapan (40)
│   ├── dialect/                # Dataset komparatif 5 dialek Prof. Mahsun (35 lema)
│   ├── stopwords/              # Stopwords terverifikasi bahasa Sasak (JSON & TXT)
│   └── benchmark/              # Benchmark referensi evaluasi akurasi
│
├── docs/                       # Dokumentasi ilmiah & naskah jurnal riset
│   ├── artikel_evaluasi_ilmiah_sasaknlp.md
│   ├── roadmap_dan_keterbatasan_riset.md
│   └── figures/                # Gambar grafik publikasi ilmiah 300 DPI (Fig 1 - Fig 5)
│
└── tests/                      # 96 Unit tests mencakup 100% komponen fungsional
```

---

## 🧪 Menjalankan Pengujian (Unit Tests)

Jalankan seluruh rangkaian unit test:

```bash
# Menggunakan test runner bawaan Python:
PYTHONPATH=src python3 -m unittest discover -s tests -v

# Atau menggunakan pytest:
PYTHONPATH=src pytest tests -v
```

Seluruh **96 unit tests** lulus dalam waktu `< 0.8` detik.

---

## 📖 Sitasi Akademik (Citation)

Jika Anda menggunakan **SasakNLP** atau dataset yang disertakan dalam penelitian, tesis, skripsi, atau publikasi ilmiah, silakan sitasi:

```bibtex
@software{sasaknlp2026,
  author    = {kodetr},
  title     = {SasakNLP: Research-Grade Natural Language Processing and Morphological Toolkit for Bahasa Sasak},
  year      = {2026},
  publisher = {Hugging Face / GitHub / PyPI},
  url       = {https://github.com/kodetr/sasaknlp}
}
```

---

## 👨‍💻 Penulis & Pengembang (Author)

- **Pengembang & Peneliti Utama**: **kodetr** ([kodetr.com](https://kodetr.com))
- **Website Resmi**: [https://kodetr.com](https://kodetr.com)
- **Repositori GitHub**: [https://github.com/kodetr/sasaknlp](https://github.com/kodetr/sasaknlp)
- **Paket PyPI**: [https://pypi.org/project/sasaknlp/](https://pypi.org/project/sasaknlp/)
- **Demo Interaktif Web**: [https://huggingface.co/spaces/kodetr/sasaknlp-demo](https://huggingface.co/spaces/kodetr/sasaknlp-demo)
- **Lisensi**: MIT Open Source

---

## 📄 Lisensi (License)

Proyek ini dilisensikan di bawah **MIT License** — lihat berkas [LICENSE](LICENSE) untuk rincian selengkapnya.


