Spaces:

ALAMDIENG
/

waste-prediction-api

Sleeping

App Files Files Community

waste-prediction-api / Doc.md

ALAMDIENG

Create Doc.md

1aa8eca verified about 2 months ago

preview code

Raw

History Blame Contribute Delete

14.9 kB

🗑️ Waste Intelligence API — Complete Documentation

AI-Powered Predictive Waste Management System for Jakarta Pusat (CASE 2)
Version: 2.0.0 | License: MIT | Author: Faril Putra Pratama - SMK Taruna Bangsa

1. Project Overview

Problem Statement

Penumpukan sampah di Jakarta Pusat sering terjadi secara mendadak saat:

️ Musim hujan tinggi (sampah basah → berat volume naik)
🎪 Event besar (PRJ, Lebaran, Konser, HUT RI)
📅 Weekend & libur nasional

Penanganan saat ini masih reaktif: armada dikirim setelah laporan masuk atau tumpukan terlihat. Akibatnya: biaya operasional membengkak, jadwal pengangkutan tidak efisien, dan risiko kesehatan lingkungan meningkat.

💡 Solution

Sistem ini mengubah paradigma menjadi prediktif menggunakan:

🤖 Amazon Chronos (Transformer time-series) untuk forecasting baseline volume
🌦️ BMKG Weather Integration untuk penyesuaian berat sampah basah
📅 Event Calendar Engine dengan location-aware impact modeling
🚛 Logistics Optimizer untuk rekomendasi armada & manpower presisi

Output: Prediksi volume sampah 1–30 hari ke depan per lokasi, dekomposisi organik/plastik, status risiko, dan rencana logistik operasional.

2. System Architecture

┌─────────────────────────────────────────────────┐
│                 CLIENT LAYER                     │
│  • Postman / Frontend Dashboard / Mobile App    │
│  • REST API Calls (JSON)                         │
└────────────────────────────────────────────────┘
              │ HTTPS / CORS
              ▼
┌─────────────────────────────────────────────────┐
│              API GATEWAY (FastAPI)              │
│  • Request Validation (Pydantic)                │
│  • CORS Middleware                              │
│  • Structured Logging                           │
└─────────────┬───────────────────────────────────┘
              │
    ┌─────────┴─────────┐
    ▼                   ▼
─────────┐     ┌─────────────┐
│ PREDICT │     │  STATUS     │
│Endpoint │     │  Check      │
└────┬────┘     └─────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│           BUSINESS LOGIC LAYER                  │
│  1️⃣ Date Parser & Context Setup                │
│  2️⃣ Chronos Inference (Async/ThreadPool)       │
│  3️⃣ External Factor Integration                │
│     • Rain multiplier (BMKG)                    │
│     • Event engine + radius mapping             │
│     • Soft impact scaling (10–35%)              │
│  4️⃣ Post-Processing & Aggregation              │
│     • KLHK 2026 decomposition                   │
│     • Risk scoring & truck calculation          │
─────────────┬───────────────────────────────────┘
              │
    ┌─────────┴─────────┐
    ▼                   ▼
┌─────────┐     ┌─────────────┐
│ DATA    │     │ MODEL       │
│ LAYER   │     │ LAYER       │
│ • CSV   │     │ • Chronos  │
│ • In-mem│     │   T5-Tiny   │
│ Cache   │     │ • PyTorch   │
└─────────┘     └─────────────┘

🔹 Tech Stack

Layer	Technology
API Framework	FastAPI + Uvicorn
AI Model	Amazon Chronos-T5-Tiny (Hugging Face)
Data Processing	Pandas, NumPy
Validation	Pydantic v2
Deployment	Hugging Face Spaces (CPU)
Logging	Python `logging` (structured)

3. Core AI & Business Logic

🤖 3.1 Time-Series Forecasting (Chronos)

Model: amazon/chronos-t5-tiny (lightweight, CPU-optimized)
Input: Historical volume series (dataset_vibe_coder_2026.csv, 365 hari)
Output: Probabilistic forecast (median quantile 0.5) untuk N hari ke depan
Advantage: Mampu menangkap pola musiman, tren gradual, dan fluktuasi natural tanpa fitur engineering berat

🎪 3.2 Event Engine & Location Matching

Event tidak serta-merta menaikkan volume di seluruh kota. Sistem menggunakan radius-aware logic:

EVENT_RADIUS_MAP = {
    'jiexpo': ['jis', 'kemayoran', 'pademangan', 'jakarta'],
    'monas': ['pasar senen', 'gang sempit tambora', 'merdeka', 'jakarta'],
    'gbk': ['senayan', 'tanah abang', 'kuningan', 'jakarta'],
    'ancol': ['pademangan', 'kelapa gading', 'jakarta'],
    'jakarta': ['*']  # City-wide
}

Matching Rules: Direct string match → City-wide fallback → Radius mapping
Impact Scaling: 1.0 + (0.10 + min(scale * 0.05, 0.25)) → Maksimal +35% volume
Result: Event di JIExpo hanya mempengaruhi JIS/Kemayoran, bukan GBK/Senayan

🌧️ 3.3 Weather Integration (BMKG Style)

Curah hujan mempengaruhi berat sampah (basah = lebih padat/berat):

≤20mm: Tidak ada penyesuaian
>20mm: Multiplier 1.02 hingga 1.05 (linear scaling)
Rationale: Sampah organik menyerap air → tonase naik tanpa volume fisik berubah drastis

️ 3.4 Risk Scoring Algorithm

def hitung_prioritas(nama_lokasi, volume_ton):
    akses = DATABASE_LOKASI[nama_lokasi]['aksesibilitas']  # 0.25 – 1.0
    skor = volume_ton / akses
    if skor > 1600: return 'CRITICAL ⚠️'
    if skor >= 1100: return 'WARNING 🟡'
    return 'SAFE ✅'

Accessibility Factor: Lokasi sempit/sulit dijangkau (0.25) mendapat skor risiko lebih tinggi untuk volume yang sama
Thresholds: Dikalibrasi untuk rentang volume realistis Jakarta Pusat (1000–2000 ton)

📊 3.5 Waste Decomposition (KLHK 2026)

Rasio dekomposisi dihitung dinamis dari dataset historis, fallback ke standar resmi:

Organik/Sisa Makanan: ~49.87%
Plastik: ~22.95%
Sisanya: Kertas, logam, residu (tidak dihitung terpisah untuk optimasi logistik)

4. API Reference

`POST /api/v1/predict`

Deskripsi: Generate prediksi volume sampah 1–30 hari ke depan untuk lokasi tertentu.

Request Body

{
  "hari_ke_depan": 7,
  "prediksi_hujan_bmkg": 25.5,
  "skala_keramaian": 0,
  "nama_lokasi": "JIS",
  "dari_tanggal": "06-01"
}

Field	Type	Required	Description
`hari_ke_depan`	`int`	✅	Durasi prediksi (1–30 hari)
`prediksi_hujan_bmkg`	`float`	✅	Estimasi curah hujan (mm). `0` = kering
`skala_keramaian`	`int`	✅	Skala event manual (0–5). `0` = normal
`nama_lokasi`	`string`	✅	Target lokasi: `JIS`, `GBK`, `Pasar Senen`, `Gang Sempit Tambora`
`dari_tanggal`	`string`	❌	Tanggal mulai. Format: `YYYY-MM-DD`, `MM-DD`, atau `"1 Juni 2026"`

Response Success (200)

{
  "status": "success",
  "message": "🟡 WARNING di JIS: Volume di atas rata-rata.",
  "confidence_score": 0.94,
  "data": {
    "prediction_results": [
      {
        "tanggal": "2026-06-02",
        "lokasi": "JIS",
        "total_volume_ton": 1245.50,
        "sisa_makanan_ton": 621.15,
        "plastik_ton": 285.84,
        "rekomendasi_truk": 125,
        "status_risiko": "WARNING 🟡",
        "info_event": "PRJ Opening @ JIExpo"
      }
    ],
    "logistics_plan": {
      "trucks_needed": 872,
      "manpower": 2616,
      "estimated_duration_hours": 1743.2,
      "efficiency_rate": "85% (Optimal)"
    }
  }
}

Error Responses

Status Code	Response	Cause
`400`	`{"detail": "Format tanggal tidak valid..."}`	Input tanggal tidak dikenali parser
`500`	`{"detail": "Gagal memproses prediksi: ..."}`	Internal error / model crash
`503`	`{"detail": "Model/Dataset belum siap."}`	Service masih startup / model loading

`GET /`

Deskripsi: Health check & metadata sistem.

{
  "status": "Online",
  "model": "Chronos-T5 Tiny",
  "dataset_year": "2026",
  "events_loaded": 15
}

5. Data Dictionary

📄 `dataset_vibe_coder_2026.csv`

Kolom	Tipe	Deskripsi
`TANGGAL`	`YYYY-MM-DD`	Hari observasi
`RR`	`float`	Curah hujan (mm)
`Nama_Event`	`string`	Nama event (kosong jika tidak ada)
`Ada_Event`	`int`	Flag `1`/`0`
`Crowd_Scale`	`float`	Skala keramaian (0–5)
`Volume_Total_Ton`	`float`	Volume sampah baseline
`Vol_Sisa_Makanan_Ton`	`float`	Komponen organik
`Vol_Plastik_Ton`	`float`	Komponen plastik
`Hari_Ke`	`int`	Urutan hari (1–365)
`Is_Weekend`	`int`	`1` = Sabtu/Minggu
`ZONA`	`string`	Klasifikasi area: `Tourism`, `Residential`, `Commercial`

📄 `event_jakarta_2026.txt`

Kolom	Tipe	Deskripsi
`tanggal`	`YYYY-MM-DD`	Tanggal event
`nama_event`	`string`	Nama event
`lokasi`	`string`	Lokasi utama event
`skala_keramaian`	`int`	Skala 1–5

6. Deployment & Setup

Hugging Face Spaces (Production)

Create Space → Template: Blank → Runtime: Python

Upload files:

📁 waste-prediction-api/
├── app.py
├── dataset_vibe_coder_2026.csv
├── event_jakarta_2026.txt
├── requirements.txt
└── SYSTEM_ARCHITECTURE.md

Settings → Python 3.10, Hardware: CPU, Auto-rebuild: ON
Click Factory rebuild after each commit

💻 Local Development

git clone https://huggingface.co/spaces/ALAMDIENG/waste-prediction-api
cd waste-prediction-api
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8001 --reload

Test:

curl -X POST http://localhost:8001/api/v1/predict \
  -H "Content-Type: application/json" \
  -d '{"hari_ke_depan":7,"dari_tanggal":"06-01","nama_lokasi":"JIS"}'

📦 `requirements.txt`

fastapi>=0.104.0
uvicorn>=0.24.0
pandas>=2.1.0
numpy>=1.26.0
torch>=2.1.0
chronos-forecasting>=0.1.0
pydantic>=2.5.0

7. Testing & Validation

🧪 Unit Tests (Conceptual)

def test_parse_flexible_date():
    assert parse_flexible_date("06-01").date() == date(2026, 6, 1)
    assert parse_flexible_date("1 Juni 2026").date() == date(2026, 6, 1)

def test_location_matching():
    assert check_location_match("JIS", "JIExpo") == True
    assert check_location_match("GBK", "JIExpo") == False

Integration Scenarios (Postman)

Scenario	Input	Expected
Normal day	`dari_tanggal: "06-10", skala: 0`	`info_event: null`, volume ~1200 ton
Event match	`dari_tanggal: "06-01", lokasi: "JIS"`	`info_event: "PRJ..."`, +20–35% volume
Event no-match	`dari_tanggal: "06-01", lokasi: "GBK"`	`info_event: null`, volume normal
Heavy rain	`prediksi_hujan_bmkg: 50`	Multiplier +2–5%
Low accessibility	`lokasi: "Gang Sempit Tambora"`	Lower volume → WARNING/CRITICAL

📈 Performance Targets

Latency: < 3.0s (p95) untuk forecast 7 hari
Throughput: 10–20 req/min (HF Spaces CPU tier)
Accuracy: ±8–12% MAE vs baseline historis (valid untuk perencanaan logistik)

8. Business Impact & Use Cases

Operational Efficiency

Metric	Before (Reactive)	After (Predictive)	Improvement
Fleet dispatch	After complaint/report	H-1/H-2 scheduled	⬇️ 15–20% idle time
Fuel cost	Unplanned routes	Optimized zoning	️ 10–12% consumption
Manpower	Overtime-heavy	Shift-planned	⬇️ 8–10% overtime
Public health	Post-spill cleanup	Pre-emptive containment	⬆️ Risk mitigation

Primary Use Cases

Dinas Lingkungan Hidup: Penjadwalan armada harian berbasis risiko zonasi
Event Organizer: Kalkulasi kebutuhan TPS & truk sampah saat izin keramaian
Fasilitas Pengelola Sampah: Alokasi shift & kapasitas gudang 3 hari ke depan
Dashboard Eksekutif: Executive summary + visual heatmap volume per kecamatan

9. Roadmap & Scalability

v2.1 (Next 3 Months)

Real-time BMKG API integration (auto-fetch prediksi_hujan_bmkg)
Batch prediction endpoint (/api/v1/predict/multi)
Export to PDF/CSV + email webhook
Rate limiting & API key auth

🏗️ v3.0 (Architecture Upgrade)

Microservices split: forecast-service, event-service, logistics-service
GPU inference optimization (Chronos-base/mini)
Automated retraining pipeline (GitHub Actions + HF Datasets)
Prometheus/Grafana observability + alerting

Long-term Vision

"Dari prediksi volume → optimasi rute real-time → circular economy tracking. Sistem ini menjadi tulang punggung smart city waste management yang data-driven, hemat biaya, dan berkelanjutan."

10. Author & Support

Developed by:
Faril Putra Pratama
SMK Taruna Bangsa
🔗 GitHub: @FARILtau72

License: MIT
Case Study: Waste Volume Prediction System (CASE 2)
Last Updated: 2026-06-01

📩 Issues & Contributions:
Gunakan GitHub Issues untuk bug report, feature request, atau dokumentasi improvement. PR welcome!

💡 Presenter Note:
"Sistem ini bukan sekadar forecast angka. Ia adalah decision engine: Chronos memberi baseline, cuaca memberi koreksi berat, event memberi konteks spasial, dan risk scoring memberi prioritas aksi. Hasilnya? Armada tidak lagi keliling buta—mereka datang ke tempat yang tepat, di waktu yang tepat, dengan kapasitas yang tepat."