# Panduan Teknis Fetty Assistant (v1.2.0)
Dokumentasi Arsitektur, Multi-Key Rotation, Vercel Serverless, dan Integrasi AI Portfolio Companion
Pengembang: Fathi Fadhil (@Fathii3) | Repositori: https://github.com/Fathii3/Cat-Bot
---
## 1. Ikhtisar Sistem
Fetty Assistant (Cat-Bot) adalah asisten virtual portofolio interaktif berbasis kecerdasan buatan (Google Gemini Flash Family) yang dibangun dengan dukungan ganda: aplikasi mandiri Python / Streamlit serta arsitektur Native Web UI dengan backend Serverless Function Vercel (/bot).
Bot ini dirancang untuk menjawab pertanyaan pengunjung seputar rekam jejak 11 proyek unggulan, keahlian teknis terspesialisasi, alur kerja rekayasa 5 fase (ide hingga rilis), 9 sertifikasi industri terverifikasi, dan kontak kolaborasi pengembang secara cepat, ramah, dan kontekstual.
Arsitektur sistem dibangun dengan pendekatan modular:
1. Engine Antarmuka Ganda (Dual Frontend):
- Native Web UI (/bot): Dibangun dengan antarmuka web modern ringan (HTML, CSS vanilla beraksen emerald, dan JavaScript modular) yang terhubung ke Vercel Serverless Function (api/knowledge.ts).
- Streamlit UI (app.py): Chat interface interaktif berbasis Python dengan tombol pintasan topik instan (st.pills), visual skeleton loading, dan palet hijau emerald (#059669).
2. Gemini Manager & Rotasi Multi-Key: Algoritma proaktif round-robin yang mendistribusikan beban percakapan ke 1 hingga 5 Google Gemini API key dengan proteksi auto-cooldown jika kuota limit (HTTP 429) tercapai.
3. Expanded Knowledge Base & In-Memory Context: Basis pengetahuan komprehensif pada knowledge/portfolio_data.py dan api/knowledge.ts mencakup metodologi alur kerja dev, profil CV lengkap, matriks skill, serta rincian problem-solving setiap proyek.
---
## 2. Informasi Rilis & Metadata
- Versi Rilis: v1.2.0 (11 Okt 2026)
- Latest Commit Hash (SHA-1): 7bbde0ee25cd4f2015bfefa1257020431a11578d
- Ringkasan Pembaruan v1.2.0:
- Dukungan Deployment Vercel & Serverless API: Integrasi endpoint serverless TypeScript (api/knowledge.ts) untuk deployment satu klik di cloud Vercel.
- Antarmuka Native Web UI (/bot): Implementasi frontend web mandiri responsif tanpa ketergantungan runtime Python saat disematkan ke web portofolio.
- Ekspansi Basis Pengetahuan (Knowledge Base RAG):
- Penambahan CV lengkap pengembang dan metodologi rekayasa 5 fase (Ideation -> Planning -> Architecture -> Execution -> QA & Ship).
- Ekspansi portofolio menjadi 11 proyek lengkap dengan rincian problem, stack, challenge, solution, dan metric hasil (termasuk Polynomial Field Calculator, Wi-Fi Connect & Network Monitoring, dan Simulasi Jaringan Cisco Packet Tracer).
- Ekspansi 9 lisensi dan sertifikasi industri lengkap dengan nomor kredensial dan URL verifikasi langsung.
- Peningkatan Kecepatan Respons: Optimasi pemanggilan model Gemini 3.1 & 3.5 Flash Lite dengan waktu respon sub-detik.
---
## 3. Fitur Utama & Keunggulan Teknis
### A. Rotasi Cerdas Multi-Key (Hingga 5 API Key)
- Mendukung konfigurasi 1 hingga 5 kunci API Gemini di file .streamlit/secrets.toml atau Vercel Environment Variables.
- Rotasi proaktif round-robin membagi beban traffic obrolan secara merata ke seluruh key yang tersedia.
- Mekanisme proteksi cooldown 60 detik otomatis menandai key yang mengalami kuota habis (HTTP 429 RESOURCE_EXHAUSTED) dan mengalihkan permintaan secara mulus ke key aktif berikutnya tanpa memutus sesi pengguna.
### B. Pemilihan Model Cepat & Efisien (Gemini Flash Family)
- Memprioritaskan model cepat generasi terbaru: gemini-3.1-flash-lite dan gemini-3.5-flash-lite untuk latensi time-to-first-token yang sangat singkat.
- Dilengkapi fallback otomatis ke model gemini-3.6-flash dan gemini-flash-latest guna menjamin keandalan uptime layanan.
### C. Persona Ramah & Dukungan Dwibahasa (ID / EN)
- Memiliki gaya tutur santai, hangat, dan bersahabat dengan persona kucing (meow~), namun tetap mempertahankan akurasi teknis tinggi saat menjelaskan arsitektur perangkat lunak.
- Deteksi dwibahasa otomatis: merespons dalam Bahasa Indonesia secara bawaan, dan beralih ke Bahasa Inggris jika pertanyaan diajukan dalam Bahasa Inggris.
### D. Pintasan Topik Cepat (One-Click Topic Shortcuts)
- Komponen st.pills menyediakan akses instan ke 6 topik utama: Projek Unggulan, Lisensi & Sertifikat, Pengalaman Kerja, Tech Stack, Repositori GitHub, dan Kontak Sosial Media.
### E. Manajemen Sesi Percakapan Multi-Chat
- Pengunjung dapat membuat sesi percakapan baru, beralih antar-sesi, atau membersihkan riwayat obrolan.
- Penamaan judul sesi diatur otomatis berdasarkan inti pertanyaan pertama pengguna.
---
## 4. Struktur Direktori Proyek
```text
Cat-Bot/
├── api/
│ └── knowledge.ts # Serverless API endpoint Vercel & knowledge base CV
├── assets/
│ ├── fetty_avatar.svg # Aset vektor avatar maskot Fetty
│ └── user_avatar.svg # Aset vektor avatar pengunjung
├── components/
│ ├── icons.py # Kamus SVG vektor ikon Lucide inlined
│ ├── shortcuts.py # Widget pintasan topik cepat (st.pills)
│ └── ui.py # Skeleton loader shimmer, alert callout, & navbar
├── knowledge/
│ └── portfolio_data.py # Basis data portofolio, keahlian, dan CV developer (Python)
├── public/
│ └── css/
│ └── style.css # Stylesheet antarmuka Native Web UI (/bot)
├── styles/
│ └── main_css.py # Custom stylesheet responsif & tema hijau emerald (Streamlit)
├── utils/
│ ├── gemini_manager.py # Rotasi multi-key, cooldown timer, & prompt builder
│ └── session_manager.py # State management riwayat percakapan pengguna
├── app.js # Controller client-side untuk Native Web UI
├── app.py # Entry point dan controller utama Streamlit
├── index.html # Halaman web mandiri Native Web UI (/bot)
├── requirements.txt # Dependensi pustaka Python
└── README.md # Dokumentasi proyek
```
---
## 5. Panduan Pemasangan & Menjalankan Lokal
### Prasyarat Lingkungan
- Python versi 3.10 atau lebih tinggi (untuk Streamlit mode).
- Node.js versi 18+ (untuk pengujian Serverless / Vercel mode).
- Minimal 1 Google Gemini API Key dari Google AI Studio (https://aistudio.google.com).
### Opsi A: Menjalankan Streamlit App (Python)
1. Kloning repositori:
```bash
git clone https://github.com/Fathii3/Cat-Bot.git
cd Cat-Bot
```
2. Buat & aktifkan virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate # atau .venv\Scripts\Activate.ps1 di Windows
```
3. Pasang dependensi:
```bash
pip install -r requirements.txt
```
4. Buat berkas konfigurasi `.streamlit/secrets.toml`:
```toml
GEMINI_API_KEY_1 = "AIzaSy..."
GEMINI_API_KEY_2 = "AIzaSy..."
```
5. Jalankan aplikasi Streamlit:
```bash
streamlit run app.py
```
Akses di browser pada `http://localhost:8501`.
### Opsi B: Menjalankan Native Web UI & Deploy ke Vercel
1. Pasang Vercel CLI (jika belum terpasang):
```bash
npm i -g vercel
```
2. Hubungkan proyek dan tambahkan Environment Variable:
```bash
vercel env add GEMINI_API_KEY
```
3. Jalankan pengujian serverless lokal:
```bash
vercel dev
```
Akses Native Web UI di `http://localhost:3000`.
---
## 6. Integrasi ke Web Portofolio Utama
Asisten dapat disematkan langsung ke situs web portofolio dengan dua pendekatan:
### 1. Integrasi Langsung Native Web UI (/bot)
Tambahkan container interaktif atau sematkan iframe ringan ke halaman portofolio:
```html
```
### 2. Integrasi Iframe Streamlit Cloud
```html
```
---
## 7. Ringkasan Spesifikasi Teknis
| Parameter | Spesifikasi |
| :--- | :--- |
| Bahasa Pemrograman | Python 3.10+ & TypeScript / JavaScript (ES6+) |
| Framework Antarmuka | Streamlit 1.35.0+ & Native Web UI (HTML5/CSS3) |
| Runtime Cloud | Vercel Serverless Functions & Streamlit Cloud |
| Provider LLM | Google Gemini (google-genai SDK & REST API) |
| Model Utama | gemini-3.1-flash-lite, gemini-3.5-flash-lite |
| Mekanisme Key Balancing | Proactive Round-Robin (Maksimal 5 API Keys) |
| Durasi Cooldown HTTP 429 | 60 Detik Otomatis |
| Aksen Visual | Emerald Green (#059669 / #10B981) |
| Cakupan Basis Pengetahuan | 11 Proyek, 9 Sertifikasi Industri, Metodologi Dev 5 Fase |
| Lisensi | Open Source (MIT / Personal Portfolio) |
---
Dokumen ini disusun untuk katalog repositori berkas dist.nex.biz.id.