PANDUAN GABUNGAN: CHATBOT + API GEMINI + BACKEND PYTHON (app.py)

============================================================
A. KENAPA SEBELUMNYA TIDAK ADA PENJELASAN PYTHON app.py?
============================================================

Sebelumnya arsitektur chatbot di project ini langsung memanggil Gemini dari Laravel (PHP)
melalui file app/Services/GeminiService.php.

Artinya:
- Tidak ada service Python terpisah.
- API key Gemini dibaca langsung dari env Laravel.

Sekarang sudah disiapkan backend Python (app.py) agar alur lebih fleksibel:
- Laravel -> Python backend -> Gemini API
- Kunci API dapat difokuskan di backend Python.


============================================================
B. STRUKTUR BARU YANG DITAMBAHKAN
============================================================

Folder baru:
- public/python_backend/app.py
- public/python_backend/requirements.txt

Perubahan konfigurasi:
- config/services.php
  tambah:
  - services.gemini.backend_url
  - services.gemini.backend_token

- .env.example
  tambah:
  GEMINI_API_KEY=
  GEMINI_BACKEND_URL=http://127.0.0.1:8001
  GEMINI_BACKEND_TOKEN=

Perubahan service Laravel:
- app/Services/GeminiService.php
  - jika GEMINI_BACKEND_URL terisi, Laravel coba kirim request ke Python backend dulu
  - jika backend Python gagal, otomatis fallback ke pemanggilan Gemini langsung (mode lama)


============================================================
C. CARA KERJA ARSITEKTUR CHATBOT SEKARANG
============================================================

1) User kirim chat dari UI Laravel.
2) ChatbotController memanggil GeminiService::chat(...).
3) GeminiService menyiapkan payload chat (contents + generationConfig).
4) Jika GEMINI_BACKEND_URL terisi:
   - request dikirim ke Python: POST /api/chat
5) Python backend mencoba model berurutan:
   - gemini-2.5-flash
   - gemini-2.0-flash
   - gemini-2.0-flash-lite
6) Jika Python sukses -> balasan dikembalikan ke Laravel.
7) Jika Python gagal -> Laravel fallback ke direct Gemini API.
8) Jika semua gagal -> fallback response lokal di GeminiService.


============================================================
D. ENDPOINT PYTHON BACKEND
============================================================

1) GET /health
   Fungsi: cek backend hidup + status key

2) POST /api/chat
   Body JSON:
   {
     "payload": { ... Gemini payload ... },
     "models": ["gemini-2.5-flash", "gemini-2.0-flash", "gemini-2.0-flash-lite"]
   }

   Response sukses:
   {
     "success": true,
     "message": "...jawaban model...",
     "model": "gemini-2.5-flash"
   }

   Response gagal:
   {
     "success": false,
     "message": "Semua model gagal",
     "error": "...detail..."
   }


============================================================
E. BATASAN / LIMIT CHATBOT (REKOMENDASI PRAKTIS)
============================================================

Saat ini yang sudah ada:
- history chat dari frontend dibatasi maksimal 20 item.
- text history dipotong maksimal 1500 karakter per item sebelum dikirim.

Batasan yang disarankan agar stabil dan hemat biaya:
1) Batasi input user per pesan (contoh: 500-1000 karakter).
2) Batasi requests per menit per user (rate limit).
3) Batasi token output (sudah ada maxOutputTokens=4096, bisa diturunkan jika perlu).
4) Simpan cooldown jika terkena 429 berulang.
5) Tetapkan timeout request (sudah ada timeout di PHP dan Python).
6) Log usage untuk audit (siapa, kapan, berapa panjang pesan).


============================================================
F. LANGKAH MENJALANKAN BACKEND PYTHON
============================================================

1) Masuk ke folder python backend
   cd public/python_backend

2) Buat virtual environment (opsional tapi disarankan)
   python -m venv .venv
   .venv\Scripts\activate

3) Install dependency
   pip install -r requirements.txt

4) Set environment variable untuk backend Python
   (PowerShell contoh)
   $env:GEMINI_API_KEY="ISI_API_KEY_GEMINI"
   $env:BACKEND_TOKEN="TOKEN_RAHASIA_BACKEND"   # opsional tapi disarankan
   $env:PY_BACKEND_HOST="127.0.0.1"
   $env:PY_BACKEND_PORT="8001"

5) Jalankan server Python
   python app.py

6) Test health endpoint
   buka: http://127.0.0.1:8001/health


============================================================
G. KONFIGURASI LARAVEL AGAR PAKAI BACKEND PYTHON
============================================================

Di .env Laravel, isi:
- GEMINI_BACKEND_URL=http://127.0.0.1:8001
- GEMINI_BACKEND_TOKEN=TOKEN_RAHASIA_BACKEND

Opsional:
- GEMINI_API_KEY=... (tetap boleh ada untuk fallback direct mode)

Setelah ubah env:
- php artisan optimize:clear


============================================================
H. KEAMANAN API KEY GEMINI
============================================================

Praktik aman:
1) Jangan hardcode API key di kode sumber.
2) Simpan API key di env backend Python.
3) Gunakan BACKEND_TOKEN agar endpoint Python tidak bisa dipakai bebas.
4) Jalankan backend Python di localhost/internal network.
5) Jangan commit file .env ke GitHub.


============================================================
I. SATU FILE RINGKAS UNTUK SIDANG (NARASI SINGKAT)
============================================================

Arsitektur chatbot awal memanggil Gemini langsung dari Laravel. Agar manajemen API key
lebih aman dan fleksibel, ditambahkan backend Python app.py sebagai gateway. Laravel
mengirim payload ke Python endpoint /api/chat, lalu Python meneruskan ke Gemini dengan
mekanisme pemilihan model bertahap. Jika backend Python gagal, Laravel tetap memiliki
mekanisme fallback ke direct Gemini sehingga layanan chatbot lebih robust. Sistem juga
menerapkan pembatasan history dan panjang pesan, dan dapat ditingkatkan dengan rate limit
per pengguna agar performa tetap stabil.


============================================================
J. CATATAN PENTING
============================================================

- Jika GEMINI_BACKEND_URL tidak diisi, sistem tetap berjalan seperti mode lama.
- Jika GEMINI_BACKEND_URL diisi tapi backend Python mati, sistem otomatis fallback direct.
- Untuk mode produksi, disarankan Python backend aktif + token + monitoring log.