---
language:
  - id
license: mit
tags:
  - cognitive-language-model
  - indonesian
  - bahasa-indonesia
  - knowledge-representation
  - explicit-reasoning
  - morphology
  - semantic-parsing
  - common-sense
  - graph-of-states
library_name: aksara
pipeline_tag: text-generation
model-index:
  - name: AKSARA-CLM-v1
    results:
      - task:
          type: text-generation
          name: Cognitive Language Modeling
        metrics:
          - name: Loss
            type: loss
            value: 1.858
          - name: Correctness (E1)
            type: accuracy
            value: 0.70
          - name: Morphology (E2)
            type: accuracy
            value: 1.00
          - name: Generalization (E3)
            type: accuracy
            value: 1.00
          - name: Inference Chain (E4)
            type: accuracy
            value: 1.00
          - name: Context Tracking (E5)
            type: accuracy
            value: 1.00
---

<div align="center">

# AKSARA

**Adaptive Knowledge & Semantic Architecture for Bahasa Representation & Autonomy**

*Framework yang menghasilkan CLM (Cognitive Language Model) — model bahasa Indonesia yang memahami makna, bukan memprediksi token.*

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![HF Model](https://img.shields.io/badge/Model-HuggingFace-yellow.svg)](https://huggingface.co/emylton/AKSARA-CLM-v1)

</div>

> *"Kami tidak mengajarkan model bahasa Indonesia. Kami membuat model lahir sebagai bahasa Indonesia."*
>
> — Emylton Leunufna

---

## Apa itu AKSARA?

AKSARA adalah **framework** yang menghasilkan **CLM (Cognitive Language Model)** — model bahasa Indonesia yang **memahami makna**, bukan memprediksi token. Jika Transformer menghasilkan LLM, maka AKSARA menghasilkan CLM. Setiap keputusan komputasi punya **justifikasi linguistik eksplisit** berdasarkan TBBBI (Tata Bahasa Baku Bahasa Indonesia).

```python
from aksara import AksaraFramework

fw = AksaraFramework.dari_kbbi("kbbi_core_v2.json")
state = fw.proses("Hakim menjatuhkan vonis kepada terdakwa.")

print(state.ringkasan())
# → status=VALID | skor=0.85 | pelanggaran=0 | morfem=6

print(state.krl_result.jelaskan())
# → Proposisi: AKSI(jatuh, agen=hakim, pasien=vonis, penerima=terdakwa)
#   Frame: VONIS_HUKUM (skor=0.92)
#   Inferensi: terdakwa STATUS_MENJADI terpidana
#              terdakwa WAJIB menjalani putusan
```

**CLM ini MEMAHAMI MAKNA** — "terdakwa menjadi terpidana" bukan di-retrieve dari database dan bukan diprediksi secara statistik, tapi **di-derive** dari aturan general: *"jika profesi hukum melakukan aksi hukum terhadap warga, maka status warga berubah"*.

---

## Transformer → LLM vs AKSARA → CLM

| Aspek | Transformer → LLM | AKSARA → CLM |
|-------|-------------------|---------------|
| **Tujuan utama** | Memprediksi token berikutnya | **Memahami makna prompt** |
| **Unit dasar** | Subword token statistik | Morfem (root + afiks TBBBI) |
| **Pengetahuan** | Implisit di miliaran bobot | Eksplisit di Knowledge Base |
| **Reasoning** | Emergent (tidak dijamin) | Forward chaining deterministik |
| **Update pengetahuan** | Retrain/fine-tune | Edit KB, langsung berlaku |
| **Interpretabilitas** | Black box | Setiap inferensi bisa dilacak |
| **Ukuran model** | 4GB — 700GB | ~5MB |
| **Hardware minimum** | GPU 8GB+ | CPU cukup (inference) |

---

## Instalasi

```bash
pip install aksara
```

Atau dari source:

```bash
git clone https://github.com/aksara-id/aksara.git
cd aksara
pip install -e .
```

### Dependensi

- Python 3.11+
- PyTorch 2.0+
- NumPy 1.24+

---

## Arsitektur Pipeline

```
Kalimat (string)
   ↓
┌─────────────────────────────────────────────────────────────┐
│ [ LPS ] Linguistic Parse System                             │
│         Dekomposisi morfem deterministik (TBBBI rules)      │
│         "mempublikasikan" → me- + publikasi + -kan          │
├─────────────────────────────────────────────────────────────┤
│ [ SFM ] Semantic Field Manifold                             │
│         Grounding semantik ke KBBI (71,211 kata, 10 domain) │
├─────────────────────────────────────────────────────────────┤
│ [ CPE ] Constraint Propagation Engine                       │
│         Evaluasi constraint morfosintaktik                  │
├─────────────────────────────────────────────────────────────┤
│ [ CMC ] Categorical Meaning Composer                        │
│         Komposisi makna kategorial                          │
├─────────────────────────────────────────────────────────────┤
│ [ TDA ] Topological Dependency Analyzer                     │
│         Analisis dependensi topologis                       │
├─────────────────────────────────────────────────────────────┤
│ [ KRL ] Knowledge Representation Layer                      │
│         Proposisi + Frame matching + Inferensi              │
└─────────────────────────────────────────────────────────────┘
   ↓
AksaraState — output terstruktur + penjelasan + inferensi
```

---

## Cara Pakai

### Analisis Kalimat

```python
from aksara import AksaraFramework

fw = AksaraFramework.dari_kbbi("kbbi_core_v2.json")
state = fw.proses("Dokter merawat pasien di rumah sakit.")

# Ringkasan
print(state.ringkasan())

# Penjelasan lengkap (bahasa Indonesia)
print(state.jelaskan())

# Analisis morfologi
for m in state.morfologi:
    print(f"  {m['teks']} → root={m['root']}, afiks={m['afiks']}")
```

### Penalaran (Inference)

```python
state = fw.proses("Petani menanam padi di sawah.")

if state.krl_result:
    krl = state.krl_result
    print(krl.jelaskan())
    # Proposisi: AKSI(tanam, agen=petani, pasien=padi, lokasi=sawah)
    # Inferensi: hasil AKAN_TERSEDIA setelah proses
    #            petani MENGHASILKAN hasil
    #            petani BERGANTUNG_PADA kondisi alam

    # Query inferensial
    for inf in krl.tanya("MENGHASILKAN"):
        print(f"  {inf.subjek} {inf.relasi} {inf.objek}")
```

### Penalaran Multi-Langkah (Chain Reasoning)

```python
from aksara.primitives.krl.wacana import JendelaWacana

fw = AksaraFramework.dari_kbbi("kbbi_core_v2.json")
wacana = JendelaWacana()

# Langkah 1: penetapan regulasi
s1 = fw.proses("Menteri menetapkan peraturan baru tentang lingkungan.")
wacana.tambah(s1)

# Langkah 2: kewajiban dari regulasi
s2 = fw.proses("Peraturan itu mewajibkan semua pabrik mengurangi emisi.")
wacana.tambah(s2)

# Query: apa kewajiban pabrik?
# → pabrik WAJIB patuhi peraturan (derived dari chain 2 aturan)
```

---

## Extend Knowledge Base (Tanpa Training)

Ini keunggulan utama AKSARA — tambah pengetahuan domain baru **langsung berlaku**:

```python
from aksara.primitives.krl.kb import KnowledgeBase, TipeEntitas, AturanDunia

kb = KnowledgeBase()

# 1. Tambah kata baru → tipe entitas
kb.tambah_kata("drone", TipeEntitas.PRODUK_TEKNOLOGI)
kb.tambah_kata("blockchain", TipeEntitas.PRODUK_TEKNOLOGI)

# 2. Tambah aturan reasoning baru
kb.tambah_aturan(AturanDunia(
    nama="TEKNOLOGI_MENGUBAH_PROSES",
    tipe_aksi="buat",
    tipe_agen=TipeEntitas.PROFESI_TEKNOLOGI,
    tipe_pasien=TipeEntitas.PRODUK_TEKNOLOGI,
    kesimpulan=[
        "pasien MENGOTOMASI proses",
        "efisiensi MENINGKAT",
    ],
    domain="teknologi", prioritas=2,
))

# Langsung bisa bernalar tentang drone — tanpa training!
```

Lihat `examples/extend_kb.py` untuk contoh lengkap.

---

## Knowledge Base Saat Ini

| Komponen | Jumlah | Deskripsi |
|----------|--------|-----------|
| **TipeEntitas** | 61 | Hierarki ontologis (profesi, institusi, lokasi, benda, abstrak) |
| **KATA_KE_TIPE** | 504 | Pemetaan kata → tipe entitas |
| **VERBA_KE_TIPE_AKSI** | 369 | Pemetaan verba → tipe aksi semantik |
| **SEMUA_ATURAN** | 32 | Aturan kausal general per domain |
| **KBBI Leksikon** | 71,211 | Kata dasar + 10 domain semantik |

### Domain yang Dicakup

Hukum, Kesehatan, Pendidikan, Pertanian, Militer, Ekonomi, Seni/Budaya, Keagamaan, Politik, Transportasi, Bencana, Sosial, Pertambangan, Maritim, Media

---

## Evaluasi

```bash
python tools/evaluasi_model.py
```

| Evaluasi | Skor | Deskripsi |
|----------|------|-----------|
| **E1** Generalisasi State | 70% | Constraint satisfaction kalimat baru |
| **E2** Morfologi Kata Baru | 100% | Dekomposisi afiks TBBBI (deterministik) |
| **E3** Kalimat Baru | 100% | Realisasi proposisi → kalimat (deterministik) |
| **E4** Penalaran KRL | 100% | Forward chaining multi-langkah |
| **E5** Wacana Lintas Kalimat | 100% | Entity tracking + resolusi referensi |
| **Total** | **94%** | |

---

## CLI

```bash
python -m aksara audit                                    # Framework audit
python -m aksara info --checkpoint ./ckpt                 # Info checkpoint
python -m aksara generate --checkpoint ./ckpt --prompt "anak membaca"
```

---

## Struktur Proyek

```
aksara/
  framework.py           ← AksaraFramework (orkestrator utama)
  config.py              ← AksaraConfig
  primitives/
    lps/                 ← Linguistic Parse System (morfologi TBBBI)
    sfm/                 ← Semantic Field Manifold (grounding KBBI)
    cpe/                 ← Constraint Propagation Engine
    cmc/                 ← Categorical Meaning Composer
    tda/                 ← Topological Dependency Analyzer
    krl/                 ← Knowledge Representation Layer
      kb.py              ← Knowledge Base (entitas, aksi, aturan)
      encoder.py         ← PropositionalEncoder
      inference.py       ← InferenceEngine (forward chaining)
      wacana.py          ← JendelaWacana (discourse tracking)
  base/
    state.py             ← AksaraState (output pipeline)
tools/
  evaluasi_model.py      ← Evaluasi E1-E5
  run_training.py        ← Training BSU/MEB
examples/
  extend_kb.py           ← Contoh extend knowledge base
```

---

## Untuk Developer: 3 Jalur Pengembangan

### Jalur 1: Pakai Pre-trained + Extend KB
- Download model pre-trained
- Tambah domain knowledge via KB API
- **Tanpa training, tanpa GPU**

### Jalur 2: Fine-tune
- Mulai dari pre-trained weights
- Tambahkan corpus domain spesifik
- Retrain BSU/MEB untuk constraint satisfaction lebih tajam

### Jalur 3: Build dari Nol
- Framework sama, ganti KB + aturan afiks
- Untuk bahasa lain (Melayu, Jawa, Sunda)

---

## Dokumentasi Tambahan

- [Panduan Corpus](docs/CORPUS_GUIDE.md)

---

## Penulis

**Emylton Leunufna**

---

## Lisensi

MIT