🤖 SILOKA AI PROJECT

"Aku tidak berilmu; yang berilmu hanyalah DIA. Jika tampak ilmu dariku, itu hanyalah pantulan dari Cahaya-Nya."

Link Repositori: https://github.com/Alghifari888/siloka_ai_project.git

⚠️ STATUS PROYEK: PROTOTYPE (TAHAP PENGEMBANGAN)

Harap diperhatikan bahwa sistem ini belum 100% sempurna. Ini adalah versi Prototype di mana UI/UX dan Fitur Utama (Klasifikasi Keluhan & Logika Satpam) sudah berjalan dan dapat diuji coba secara langsung. Akurasi AI akan terus berkembang seiring dengan penambahan dataset.

📸 Proof of Concept (POC)

Berikut adalah tampilan antarmuka SILOKA AI saat melakukan klasifikasi:
(Catatan: "Coming Soon")

![POC 1 - Tampilan Normal/Multi-Label](link_gambar_poc1.png)
![POC 2 - Tampilan Safety Alert (PPKS)](link_gambar_poc2.png)
![POC 3 - Tampilan OOT/Filter Pencurian](link_gambar_poc3.png)

📑 DAFTAR ISI

1. Penjelasan Sistem

SILOKA AI adalah sebuah ekosistem cerdas yang memadukan aplikasi mobile dan kecerdasan buatan (Artificial Intelligence) untuk menyaring, mengklasifikasikan, dan merespons keluhan mahasiswa di lingkungan kampus. Sistem ini terbagi menjadi dua bagian utama:

Backend (Otak & Satpam Keamanan): Dibangun menggunakan Python dan Flask. Backend bertugas memproses teks, melakukan penyaringan kata kunci tingkat tinggi (Hard Rules), dan menjalankan model Machine Learning untuk menentukan kategori laporan.
Frontend (Wajah & Interaksi): Dibangun menggunakan Flutter. Berfungsi sebagai antarmuka pengguna yang ramah, mengambil input teks keluhan, mengirimkannya ke Backend, dan menampilkan hasil analisis (persentase, peringatan bahaya, atau alasan AI) secara dinamis.

2. Tujuan Utama

Efisiensi Penanganan Keluhan (Backend): Mencegah laporan yang salah sasaran (misal: curhatan pribadi masuk ke bagian IT) dengan menggunakan filter cerdas.
Prioritas Keamanan Mahasiswa (Sistem): Memastikan laporan yang mengandung unsur pelecehan, ancaman, atau trauma langsung diprioritaskan ke Satgas PPKS tanpa harus melewati antrean analisis reguler.
Transparansi & Kemudahan (Frontend): Memberikan transparansi kepada pengguna (mahasiswa) mengapa laporan mereka masuk ke kategori tertentu melalui fitur Reasoning/Notes yang mudah dibaca.

3. Deskripsi Proyek

Proyek ini mengimplementasikan metode klasifikasi teks hibrida. Kami tidak hanya bergantung pada probabilitas Machine Learning murni, melainkan menggabungkannya dengan "Logika Satpam" (Hard Rules) berbasis Regex.
Jika pengguna melaporkan kerusakan AC, Machine Learning akan memprosesnya sebagai masalah "Sarpras". Namun, jika ada kata kunci pencurian (maling/dicuri), "Logika Satpam" akan mencegat laporan tersebut sebelum masuk ke Machine Learning dan memaksanya menjadi kategori "OOT" (Out of Topic/Kriminal Umum), sehingga teknisi IT tidak direpotkan dengan kasus pencurian laptop.

4. Alur Kerja Sistem

Berikut adalah alur bagaimana sistem memproses satu laporan dari awal hingga akhir:

Frontend: Pengguna mengetik keluhan di aplikasi Flutter dan menekan tombol "Analisis Laporan".
API Request: Frontend mengirimkan JSON berisi teks ke endpoint /predict di Backend Flask.
Backend (Filter Keamanan 1): Teks dicek menggunakan Regex untuk mendeteksi unsur PPKS (pelecehan/ancaman). Jika ya, langsung kembalikan label "Satgas PPKS" beserta catatannya.
Backend (Filter Keamanan 2): Jika bukan PPKS, teks dicek untuk unsur IT Support. Namun, jika di dalamnya terdapat kata kunci pencurian (hilang, maling), sistem akan menolak masuk ke IT dan merespons dengan label "OOT".
Backend (Machine Learning): Jika laporan lolos dari kedua filter di atas, teks dibersihkan (Preprocessing) dan diumpankan ke model SGDClassifier. Model mengembalikan persentase probabilitas (misal: Keuangan 60%, Akademik 40%).
Frontend (Decision UI): Flutter menerima hasil. Jika probabilitas tertinggi > 65%, aplikasi menampilkan UI warna Hijau (Yakin). Jika < 65%, aplikasi menampilkan daftar persentase (Multi-Topik). Jika mendapat status Safety Alert, layar akan menampilkan peringatan Merah.

5. Fitur Utama

Di Sisi Frontend (Aplikasi Mobile):

Server Connection Checker: Indikator real-time apakah server AI sedang online atau offline.
Dynamic UI Response: Tampilan yang berubah sesuai tingkat bahaya atau keyakinan AI (Kotak Merah untuk Bahaya, Hijau untuk Yakin, Tabel untuk Multi-topik).
Character Limiter Toggle: Sakelar untuk mewajibkan pelapor menulis minimal 300 karakter agar keluhan lebih detail.
AI Reasoning Display: Menampilkan alasan (notes) mengapa AI memilih kategori tersebut.

Di Sisi Backend (Server AI):

Satpam PPKS (Safety Override): Deteksi darurat berbasis Regex untuk isu kekerasan seksual.
Theft Blocker (Filter Kriminal): Mencegah kasus pencurian masuk ke antrean layanan teknis kampus.
Super Preprocessing: Modul pembersih teks, normalisasi kata gaul (kamus kustom), dan penghapusan stopwords.
Multi-Label Output: Mampu mengukur dua topik sekaligus jika keluhan mengandung masalah campuran (misal: Uang UKT dan Error Website).

6. Teknologi yang Digunakan & Algoritma

Frontend:

Framework: Flutter (Dart).
Libraries: google_fonts, http (untuk komunikasi REST API).

Backend & Data Science:

Framework: Flask & Flask-CORS (Python).
Machine Learning Library: Scikit-Learn, Pandas, NumPy, Joblib.
Algoritma NLP: * TfidfVectorizer (N-gram 1,2) untuk ekstraksi fitur teks menjadi vektor angka.
SGDClassifier (Stochastic Gradient Descent) dengan konfigurasi loss='hinge' (Linear SVM) untuk pemisahan kelas klasifikasi.
CalibratedClassifierCV (metode Sigmoid) untuk mengubah output SVM menjadi probabilitas persentase yang mudah dibaca oleh Flutter.
Metode Logika: Hibrida (Regex Hard Rules + NLP Classification).

7. Struktur File dan Folder

Secara garis besar, struktur proyek ini terbagi menjadi dua direktori utama:

siloka_ai_project/
├── backend_ai/                  # Folder Server Python
│   ├── app.py                   # Jantung Backend Flask & API Routes
│   ├── train_model.py           # Script untuk melatih & menyeimbangkan model ML
│   ├── dataset.csv              # Database teks keluhan untuk proses belajar AI
│   ├── data/
│   │   └── siloka_model.pkl     # File model AI (hasil generate train_model.py)
│   └── requirements.txt         # Daftar library Python
│
└── frontend_flutter/            # Folder Aplikasi Mobile Flutter
    ├── lib/
    │   ├── main.dart            # Entry point aplikasi Flutter
    │   ├── models/
    │   │   └── ai_response.dart # Struktur data JSON (Label, Predictions, Status, Notes)
    │   ├── screens/
    │   │   └── home_screen.dart # Antarmuka utama (UI Logika & Tampilan)
    │   └── services/
    │       └── api_service.dart # Jembatan komunikasi HTTP ke backend (Ngrok)
    └── pubspec.yaml             # Konfigurasi library Flutter

8. Panduan Instalasi (Development Lokal)

Ikuti langkah-langkah ini secara berurutan agar sistem dapat berjalan di komputer lokal Anda.

A. Persiapan Backend (Terminal 1)

Buka terminal/command prompt dan clone repositori ini:

git clone https://github.com/Alghifari888/siloka_ai_project.git
cd siloka_ai_project/backend_ai

Buat dan aktifkan Virtual Environment (Sangat disarankan):

python -m venv venv
# Di Windows:
venv\Scripts\activate
# Di Mac/Linux:
source venv/bin/activate

Install semua dependencies:

pip install flask flask-cors pandas scikit-learn joblib numpy

Latih Model AI Anda: Jalankan script ini agar siloka_model.pkl tercipta dari dataset.csv.

python train_model.py

Jalankan Server Flask:

python app.py

(Biarkan terminal ini menyala. Server akan berjalan di http://localhost:5000 atau 127.0.0.1:5000)

B. Setup NGROK (Terminal 2 - Penting!)

Karena HP/Emulator Android tidak bisa membaca localhost dari komputer, kita menggunakan Ngrok untuk membuat tunnel publik.

Download dan instal Ngrok dari situs resminya.
Buka terminal baru (Terminal 2), lalu jalankan perintah:

ngrok http 5000

Salin URL publik yang diakhiri dengan .ngrok-free.app (Contoh: https://abcd-123.ngrok-free.app). Jangan matikan terminal ini.

C. Persiapan Frontend Flutter (Terminal 3 / VS Code)

Buka folder frontend di editor Anda (VS Code/Android Studio).
Buka file lib/services/api_service.dart.
Ganti variabel URL dengan URL Ngrok yang baru saja Anda salin (jangan lupa tambahkan /predict dan / di tempat yang sesuai).
Jalankan aplikasi Flutter:

flutter pub get
flutter run

9. Deployment ke VPS / Cloud Server

Untuk mempublikasikan Backend ini agar online 24 jam tanpa Ngrok:

Siapkan VPS (Ubuntu direkomendasikan).
Install Python3, Pip, dan Nginx.
Clone repositori ini ke dalam VPS.
Gunakan Gunicorn sebagai production server pengganti Flask development server:

pip install gunicorn
gunicorn --bind 0.0.0.0:5000 app:app

Gunakan PM2 atau Systemd untuk memastikan Gunicorn berjalan di background dan otomatis restart jika server mati.
Konfigurasikan Nginx sebagai Reverse Proxy untuk merutekan port 80/443 (HTTP/HTTPS) ke port 5000.
Di sisi Flutter, ganti link Ngrok dengan IP Public VPS atau Domain Anda.

10. Panduan Penggunaan & Testing

Aplikasi siap disiksa! Cobalah skenario pengujian berikut di aplikasi Flutter:

Tes Satgas PPKS: Ketik laporan yang mengandung kata "meraba" atau "direkam". Layar harus seketika menampilkan kotak merah peringatan PPKS.
Tes Filter Kriminal (OOT): Ketik laporan yang berisi "Admin, laptop saya hilang dicuri maling di lab wifi". Layar harus menolak masuk ke IT dan memberikan kotak abu-abu "Laporan Tidak Valid".
Tes Multi-Topik: Ketik "Website pembayaran error terus padahal saya mau bayar tagihan UKT". Layar harus menampilkan persentase pembagian antara Keuangan dan IT Support.

11. Alur Kerja Standar (Maintenance)

Jika AI mulai sering salah menebak, Anda perlu menambah dataset. Alurnya:

Buka file backend_ai/dataset.csv.
Tambahkan baris data baru dengan format ("Teks laporan keluhan", "Label Kategori") di baris paling bawah. Pastikan keseimbangan jumlah data.
Buka terminal dan jalankan kembali python train_model.py.
Setelah muncul tulisan "Selesai. Simpan Model...", restart server Flask Anda (python app.py).
Otak AI telah terbarui!

12. Panduan Kontribusi (Fork) & Fitur Khusus

Fitur Khusus yang sudah terpasang di rilis ini:

Auto-Correct Prioritas Dataset: Script train_model.py memiliki fitur cerdas yang otomatis memperbaiki label dataset yang typo atau salah letak (misal: "Ruang" tidak akan dilabeli sebagai "Keuangan" meskipun mirip dengan kata "Uang").

Cara Berkontribusi:

Lakukan Fork repositori ini.
Buat branch fitur Anda (git checkout -b fitur-keren-saya).
Lakukan Commit perubahan Anda (git commit -m 'Menambahkan fitur ABC').
Push ke branch tersebut (git push origin fitur-keren-saya).
Buat Pull Request baru.

13. Lisensi & Kreator

Dibuat dengan ❤️ dan ☕ oleh Alghifari888.

📄 This project is licensed under the MIT License.
(Artinya: Anda bebas menggunakan, menyalin, memodifikasi, menggabungkan, menerbitkan, mendistribusikan, dan menjual salinan proyek ini, asalkan Anda tetap mencantumkan pemberitahuan hak cipta dan lisensi asli dari pembuatnya.)

Alghifari888/siloka_ai_project