File size: 5,998 Bytes
71b7a02 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 |
# Dokumentasi Backend Sentimind (API)
Dokumen ini menjelaskan struktur folder `api`, fungsi dari setiap file, dan logika perhitungan yang digunakan dalam sistem Sentimind.
## 📂 Struktur Folder
```
api/
├── index.py # Entry point utama aplikasi (FastAPI)
├── predict.py # Endpoint untuk prediksi teks manual
├── quiz.py # Endpoint untuk sistem kuis MBTI
├── core/
│ ├── chatbot.py # Logic Chatbot menggunakan Google Gemini
│ ├── nlp_handler.py # Logic utama NLP (Machine Learning + Youtube)
│ └── quiz_logic.py # Perhitungan skor dan logika MBTI
└── data/
├── questions.json # Database soal kuis
├── model_mbti.pkl # Model Machine Learning untuk MBTI
└── model_emotion.pkl # Model Machine Learning untuk Emosi
```
---
## 🧠 Logika Perhitungan Kuis (MBTI Scoring)
Perhitungan MBTI dilakukan di file `api/core/quiz_logic.py`. Sistem tidak menggunakan sistem "benar/salah", melainkan sistem **Dimensi Bipolar**.
### 1. Variabel Dimensi
Kita memiliki 4 variabel skor awal yang dimulai dari angka 0:
- `EI`: Introvert vs Extravert
- `SN`: Sensing vs Intuition
- `TF`: Thinking vs Feeling
- `JP`: Judging vs Perceiving
### 2. Rumus Per Soal
Setiap soal memiliki atribut `dimension` (misal "EI") dan `direction` (1 atau -1).
User memberikan jawaban dalam skala -3 sampai 3 (Sangat Tidak Setuju s.d. Sangat Setuju).
**Rumus:**
```python
Skor Dimensi += (Jawaban User * Arah Soal)
```
**Contoh Kasus:**
- **Soal**: "Saya suka pesta."
- Dimensi: `EI`
- Arah (`direction`): `1` (Positif mengarah ke Extravert)
- **Jawaban User**: `3` (Sangat Setuju)
- **Hitungan**: `3 * 1 = 3`. Skor EI bertambah +3 (Makin E).
- **Soal**: "Saya butuh waktu sendiri."
- Dimensi: `EI`
- Arah (`direction`): `-1` (Positif mengarah ke Introvert)
- **Jawaban User**: `3` (Sangat Setuju)
- **Hitungan**: `3 * -1 = -3`. Skor EI berkurang -3 (Makin I).
### 3. Penentuan Hasil Akhir
Setelah menghitung total skor dari 40 soal, hasil ditentukan berdasarkan tanda positif/negatif:
| Dimensi | Skor Positif (>= 0) | Skor Negatif (< 0) |
| :------ | :------------------ | :----------------- |
| **EI** | **E** (Extravert) | **I** (Introvert) |
| **SN** | **S** (Sensing) | **N** (Intuition) |
| **TF** | **T** (Thinking) | **F** (Feeling) |
| **JP** | **J** (Judging) | **P** (Perceiving) |
---
## 📜 Penjelasan File & Fungsi (Detail)
### 1. `api/index.py`
File utama untuk menjalankan server backend.
- **`app = FastAPI()`**: Inisialisasi aplikasi.
- **`startup_event()`**: Mengecek keberadaan `YOUTUBE_API_KEY` saat server nyala. Menentukan mode Official atau Scraping.
- **`app.add_middleware(CORSMiddleware)`**: Mengizinkan frontend (berbeda port) untuk mengakses API ini.
- **Routes**: Mendaftarkan URL endpoint dari file lain (`/api/predict`, `/api/quiz`, dll).
- **`analyze_youtube_video(video_id)`**: Endpoint khusus untuk analisis YouTube. Memanggil `NLPHandler` untuk mengambil transkrip/komentar dan melakukan prediksi.
### 2. `api/predict.py`
Handler untuk fitur "Analyzer" (Input Teks Manual).
- **`predict_endpoint(input_data)`**: Menerima JSON `{ "text": "..." }`, memvalidasi input, lalu memanggil `NLPHandler.predict_all` untuk mendapatkan hasil MBTI dan Emosi.
### 3. `api/quiz.py`
Handler untuk fitur "Quiz".
- **`get_quiz_questions()`**: Mengambil daftar soal dari `QuizHandler`.
- **`submit_quiz(submission)`**: Menerima jawaban user dan mengembalikan hasil MBTI.
### 4. `api/core/chatbot.py`
Otak dari fitur Chatbot.
- **`__init__`**: Menghubungkan ke Google Gemini API. Menggunakan model `gemini-2.0-flash` atau fallback ke `lite`.
- **`generate_response(user_query, lang)`**:
- Membuat `system_prompt` yang mendefinisikan persona AI "Sentimind".
- Menyesuaikan gaya bahasa (Slang Jakarta untuk ID, Formal untuk EN).
- Mengirim prompt ke Gemini dan mengembalikan teks balasan.
### 5. `api/core/nlp_handler.py` (Core Logic)
File paling kompleks yang menangani Machine Learning dan pemrosesan data.
**Fungsi Utama:**
- **`load_models()`**: Memuat file `.pkl` (model ML yang sudah dilatih) ke memory agar prediksi cepat.
- **`_validate_with_gemini(text, ml_prediction)`**:
- Teknik **Hybrid AI**: Menggunakan LLM (Gemini) untuk "mengoreksi" hasil Machine Learning klasik.
- Jika teks cukup panjang (>50 kata), Gemini akan menganalisis ulang teks dan memberikan "second opinion".
- Mengembalikan confidence score dan alasan logis.
- **`predict_all(raw_text)`**:
1. Translate teks ke Inggris (karena model dilatih pakai B.Inggris).
2. Prediksi MBTI pakai Model ML.
3. Validasi MBTI pakai Gemini (jika memungkinkan).
4. Prediksi Emosi pakai Model ML + Normalisasi probabilitas.
5. Ekstrak Keyword utama.
6. Generate penjelasan/reasoning untuk ditampilkan di UI.
- **`fetch_youtube_transcript(video_id)`**:
- Mencoba pakai **Official YouTube API** dulu (ambil judul, deskripsi, komentar).
- Jika gagal/tak ada key, fallback ke **Scraping** (ambil subtitle otomatis).
### 6. `api/core/quiz_logic.py`
Logic pemrosesan kuis.
- **`get_questions()`**: Membaca file `api/data/questions.json`.
- **`calculate_mbti(answers)`**: Mengimplementasikan rumus scoring MBTI (lihat bagian Logika Perhitungan Kuis di atas).
---
## 🛠 Flow Data (E2E)
1. **Frontend** kirim data (Teks/Jawaban Kuis/Video ID) ke **Backend**.
2. **Backend** (`index.py` / `quiz.py` / `predict.py`) terima request.
3. **Core Logic** (`NLPHandler` / `QuizHandler`) memproses data:
- Load Model ML.
- Hitung Matematika / Prediksi Statistik.
- Panggil External API (Gemini/YouTube) jika perlu.
4. **Backend** membalas dengan JSON standar:
```json
{
"success": true,
"mbti": "INTJ",
"emotion": { "id": "Senang", "en": "Joy" },
"reasoning": { ... }
}
```
5. **Frontend** menampilkan animasi dan hasil ke user.
|