Update README.md

README.md

@@ -1,12 +1,101 @@
+# 🌍 Eco-Twin AI: Waste Volume Prediction System
+**Proyek untuk Hackathon DKI Jakarta 2025 (Case 2)**
+
+Eco-Twin AI adalah sistem cerdas berbasis *Machine Learning* yang dirancang untuk memprediksi lonjakan volume timbulan sampah harian di area Jakarta Pusat. Sistem ini menggunakan arsitektur ganda: **Amazon Chronos-T5** (Time-Series Transformer) untuk peramalan (*forecasting*) dan integrasi Algoritma Pendukung untuk ekstraksi fitur lanjutan (Cuaca, Skala Keramaian, dan Jadwal Event).
+
+---
+
+## 🚀 Fitur Unggulan (Hackathon Killer Features)
+
+1. **Integrasi Kalender Event Otomatis**: Sistem secara otomatis membaca file `event_jakarta_2025.txt` saat server dinyalakan. Jika ada *request* prediksi yang menyentuh tanggal konser besar (misal: Maroon 5 di JIS), AI akan mendeteksi dan secara akurat menambahkan estimasi volume sampah tanpa input manual tambahan.
+2. **Asynchronous API Processing**: Menggunakan FastAPI dengan `run_in_threadpool`, memastikan sistem AI tidak memblokir (*blocking*) pengguna lain saat sedang mengolah model Transformer yang berat.
+3. **Standar Produksi (CORS & Logging)**: Aplikasi aman dipanggil secara langsung oleh Frontend (React/Vue/HTML) dan menggunakan sistem *logging* kelas enterprise.
+4. **Interactive API Docs (Swagger UI)**: Endpoint dilengkapi parameter Pydantic lengkap beserta contoh JSON terisi otomatis, sangat cocok untuk didemokan langsung ke Juri.
+5. **Dekomposisi Sampah SIPSN KLHK 2025**: Memprediksi bukan hanya berat total (Ton), tapi juga membedahnya menjadi *Sisa Makanan* dan *Plastik*, serta memberikan rekomendasi jumlah armada truk yang dibutuhkan.
+
 ---
-title: Waste Prediction Api
-emoji: 🏢
-colorFrom: purple
-colorTo: pink
-sdk: docker
-pinned: false
-license: mit
-short_description: waste
+
+## 📂 Struktur File
+
+- `app.py` : Berisi *Core Engine* API menggunakan FastAPI dan Amazon Chronos.
+- `train.py` : Script *Advanced Feature Engineering* dan pelatihan model Gradient Boosting (Eco-Twin Pro) untuk simulasi dataset.
+- `event_jakarta_2025.txt` : *Database* kalender event yang otomatis dilacak oleh AI.
+- `dataset_vibe_coder_2025.csv` : Dataset historis yang dipakai oleh model.
+- `.dockerfile` : Konfigurasi untuk men-*deploy* aplikasi ini (misalnya ke Hugging Face Spaces atau server Cloud).
+- `requirements.txt` : Daftar dependensi *library* Python.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## 🛠️ Cara Menjalankan Sistem
+
+### 1. Instalasi Kebutuhan (Library)
+Pastikan Python sudah terinstal di laptop Anda. Buka Terminal/Command Prompt di dalam folder proyek ini, lalu jalankan:
+```bash
+pip install -r requirements.txt
+pip install chronos-forecasting
+```
+
+### 2. Menjalankan Server API
+Jalankan server Uvicorn dengan mode *auto-reload* agar perubahan kode langsung terbaca:
+```bash
+uvicorn app:app --reload --port 8001
+```
+
+### 3. Menguji via Swagger (Demonstrasi Juri)
+Setelah server berjalan, buka browser dan akses:
+👉 **[http://127.0.0.1:8001/docs](http://127.0.0.1:8001/docs)**
+
+Anda bisa menekan tombol **"Try it out"** di *endpoint* `/api/v1/predict` dan langsung tekan **"Execute"**.
+
+---
+
+## 📡 Dokumentasi Endpoint API
+
+### 1. Status Check
+Mengecek apakah server hidup dan berapa banyak jadwal event yang berhasil dimuat oleh AI.
+- **URL**: `/`
+- **Method**: `GET`
+- **Response**:
+```json
+{
+  "status": "Online",
+  "model": "Chronos-T5 Tiny",
+  "region": "Jakarta Pusat",
+  "events_loaded": 15
+}
+```
+
+### 2. Prediksi Volume Sampah (Forecasting)
+Mendapatkan peramalan volume sampah berdasarkan data historis, cuaca, dan event.
+- **URL**: `/api/v1/predict`
+- **Method**: `POST`
+- **Body Request**:
+```json
+{
+  "hari_ke_depan": 7,
+  "prediksi_hujan_bmkg": 25.5,
+  "skala_keramaian": 0
+}
+```
+- **Response JSON**:
+```json
+[
+  {
+    "tanggal": "2025-02-01",
+    "total_volume_ton": 1520.45,
+    "sisa_makanan_ton": 758.25,
+    "plastik_ton": 348.94,
+    "rekomendasi_truk": 153,
+    "status_risiko": "CRITICAL ⚠️",
+    "info_event": "Konser Maroon 5 di Jakarta International Stadium (JIS)"
+  }
+]
+```
+
+---
+
+## 📝 Catatan Penting
+- Jika Anda mendapatkan error `ModuleNotFoundError: No module named 'chronos'`, pastikan Anda menginstal package dengan perintah `pip install chronos-forecasting` **(BUKAN pip install chronos)**.
+- Untuk deployment dengan `Dockerfile`, pastikan untuk mengubah port Uvicorn menyesuaikan provider (misal: HuggingFace Spaces menggunakan `--port 7860`).
+
+