README.md

---
title: Freshly Universal API
colorFrom: green
colorTo: pink
sdk: docker
pinned: false
license: mit
---

# FRESHLY Universal API

Selamat datang di repositori backend resmi **FRESHLY API**! 

API ini dibangun menggunakan **FastAPI** dan ditenagai oleh model Deep Learning kustom (arsitektur *CNN dengan Spatial Attention*) yang dilatih dari nol (*Training from Scratch*). API ini berfungsi sebagai otak utama aplikasi FRESHLY untuk mengklasifikasikan jenis buah/sayur beserta tingkat kematangannya guna mengurangi *food waste*.

## 🧠 Spesifikasi Arsitektur Model
Berbeda dengan API pada umumnya yang menggunakan *Pre-trained Model* (Transfer Learning), model AI FRESHLY dibangun 100% dari awal. Keunggulan utama model kami terletak pada penggunaan **Spatial Attention Layer** buatan sendiri. 

Fitur ini memungkinkan "mata" AI kami untuk berfokus pada titik-titik krusial pada gambar (seperti bercak hitam pembusukan atau transisi warna mentah ke matang), mengabaikan *background* yang tidak penting, dan menghasilkan akurasi prediksi yang sangat tinggi.

## 🛠️ Tech Stack & Teknologi
* **Framework Backend:** FastAPI, Uvicorn
* **Machine Learning:** TensorFlow, Keras
* **Arsitektur Utama:** Custom CNN Cascade System
* **Deployment:** Docker, Hugging Face Spaces

## 📚 Dokumentasi Interaktif & Uji Coba (Swagger UI)

Bagi tim Frontend atau penguji yang ingin langsung mencoba mengunggah gambar ke AI tanpa perlu menulis kode, silakan akses halaman Swagger UI kami di bawah ini:

👉 **[Buka Halaman Uji Coba API Interaktif (/docs)](https://freshlyteam-freshly-api.hf.space/docs)** ---

## 🚀 Daftar Endpoint

### 1. Health Check
Endpoint ini digunakan untuk memastikan server dalam keadaan aktif (cocok dihubungkan dengan *UptimeRobot* untuk mencegah *cold start*).
* **URL:** `/health`
* **Method:** `GET`
* **Response:** JSON berisi status server.

### 2. Predict Freshness (Main AI)
Endpoint utama untuk mendeteksi tingkat kematangan buah/sayur. Untuk menjaga akurasi tertinggi, API ini membutuhkan jenis buah yang dipilih oleh pengguna sebagai parameter.
* **URL:** `/predict`
* **Method:** `POST`
* **Body:** `multipart/form-data` 
  * `fruit_type` (String): Tulis salah satu dari kelas yang didukung (contoh: banana, mango, chili).
  * `file` (File): File gambar buah/sayur.
* **Response Contoh:**
  ```json
  {
    "status": "success",
    "data": {
      "detected_fruit": "banana",
      "condition": "ripe",
      "condition_confidence": 98.5
    }
  }

## 💻 Panduan Integrasi (Untuk Tim Frontend)

Berikut adalah contoh implementasi pemanggilan API `/predict` menggunakan **JavaScript (Fetch API)** di sisi *client*:

```javascript
// 1. Ambil elemen dari HTML
const fileInput = document.getElementById('imageInput');
const file = fileInput.files[0];
const selectedFruit = "banana"; // Sesuai pilihan user di UI (dropdown/icon)

// 2. Siapkan form data
const formData = new FormData();
formData.append("fruit_type", selectedFruit); // Wajib dikirimkan!
formData.append("file", file);

// 3. Panggil API Freshly
fetch("https://freshlyteam-freshly-api.hf.space/predict", {
    method: "POST",
    body: formData
})
.then(response => response.json())
.then(result => {
    console.log("Status:", result.status);
    console.log("Kondisi Buah:", result.data.condition);
})
.catch(error => {
    console.error("Terjadi kesalahan:", error);
});
```
***(Catatan: Ganti URL freshlyteam-freshly-api.hf.space dengan URL Direct Space kalian jika ada perubahan).***

## 🍎 Parameter `fruit_type` yang Valid

Sangat penting bagi tim Frontend atau Penguji untuk mengirimkan **`fruit_type`** dengan ejaan huruf kecil yang tepat. **Saat ini, model kami mendukung 6 kelas berikut:**

* **`banana` (Pisang)**
* **`mango` (Mangga)**
* **`orange` (Jeruk)**
* **`chili` (Cabai)**
* **`paprika` (Paprika)**
* **`tomato` (Tomat)**

*Sistem akan mengembalikan error 400 (Bad Request) atau 422 (Validation Error) jika memasukkan jenis buah selain daftar di atas.*

## ⚙️ Cara Menjalankan Server di Local (Local Development)

Jika tim Frontend ingin menguji API ini secara offline di komputer masing-masing:
```bash
# 1. Clone repository
git clone https://huggingface.co/spaces/freshlyTeam/freshly-api

# 2. Install library yang dibutuhkan
pip install -r requirements.txt

# 3. Jalankan server lokal
uvicorn main:app --reload
```
*Server akan berjalan di `http://127.0.0.0:8000`. Akses `http://127.0.0.0:8000/docs` untuk Swagger UI lokal.*

**Developed with 🔥💪 by Tim AI FRESHLY - Coding Camp powered by DBS Foundation 2026**