Sync from GitHub Actions: b8f51c1e658e26be2f6768ab95b2b6c004c56131

api/API DOCUMENTATION.md

@@ -0,0 +1,158 @@
+# 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.