adamnwr/ml-insight-microservice

🧠 ML Insight Microservice (Capstone Project)

Microservice ini bertugas menganalisis pola belajar pengguna menggunakan Deep Learning dan Heuristic Rules. Service ini memberikan label gaya belajar (Fast, Consistent, Reflective) serta pesan motivasi yang dipersonalisasi.

🚀 Perubahan Arsitektur (New Push Architecture)

Mulai versi 2.0, service ini menggunakan metode PUSH DATA. Backend Node.js bertanggung jawab untuk mengirimkan ("Push") data statistik ke service ini. ML Service tidak lagi melakukan request balik ke Backend/Database.

Flow: Backend (Node.js) ➡️ Kirim JSON (POST) ➡️ ML Service (Python) ➡️ Response Insight

📖 API Documentation

Dokumentasi interaktif (Scalar/OpenAPI) tersedia di:

• —Local: http://localhost:7860/docs
• —Production: https://adamnwr-ml-insight-microservice.hf.space/docs

🔌 Main Endpoint

`POST /api/predict/{user_id}`

Endpoint ini menerima paket data statistik, memprosesnya, dan mengembalikan profil belajar.

Request Headers

Request Body (JSON Payload)

Backend WAJIB mengirimkan struktur berikut:

{
  "stats": {
    "avg_study_duration_hours": 1.5,    // Rata-rata durasi per modul (Jam)
    "total_tutorial_completed": 15,     // Jumlah materi selesai
    "total_study_days": 5,              // Jumlah hari aktif belajar
    "consistency_score": 4.2,           // Standar Deviasi aktivitas (0 = Sangat Konsisten)
    "avg_exam_score": 85.0              // Rata-rata nilai ujian
  },
  "user_profile": {
    "name": "Budi Santoso"              // Nama user untuk sapaan personal
  }
}

Catatan: Jika ada field yang kosong/null, ML Service akan otomatis mengisinya dengan 0 (Zero Imputation) agar tidak crash.

Response (Success - 200 OK)

{
  "status": "success",
  "data": {
    "classification": "Consistent Learner",
    "content": {
      "title": "Sang Konsisten 🏃",
      "message": "Halo Budi Santoso, kekuatan utamamu adalah disiplin. Grafik belajarmu stabil...",
      "action": "Pertahankan streak belajarmu!"
    },
    "meta": {
      "ai_confidence": "98.50%",
      "data_stability": "High",
      "disclaimer": "Analisis ini menggunakan model statistik beta."
    }
  }
}

Error Responses

• —400 Bad Request: JSON Body tidak memiliki object stats.
• —401 Unauthorized: Token tidak dikirim.
• —403 Forbidden: Token salah.
• —500 Internal Server Error: Terjadi kesalahan pada logika model.

🛠️ Instalasi & Menjalankan Lokal

1. 1.Clone Repository

    git clone <repo_url>
    cd ml-insight-microservice

1. 1.Buat Virtual Environment

    python -m venv venv
    # Windows
    venv\Scripts\activate
    # Mac/Linux
    source venv/bin/activate

1. 1.Install Dependencies

    pip install -r requirements.txt

1. 1.Setup Environment Variables (.env) Buat file .env di root folder:

    ML_SERVICE_TOKEN=ML_LearnInsight_A25

1. 1.Jalankan Server

    python app.py

Server akan berjalan di http://0.0.0.0:7860.

📂 Struktur Proyek

.
├── artifacts/              # Model .keras dan Scaler .pkl
├── core/
│   ├── ai_engine.py        # Class untuk load model & predict
│   └── config.py           # Konfigurasi & Threshold Bisnis
├── services/
│   └── insight_service.py  # Logic Utama (Gatekeeper, Mapping, Storytelling)
├── app.py                  # Entry Point (Flask API Routes)
├── requirements.txt
└── README.md

🧠 Logika Bisnis (Insight Logic)

Sistem ini menggunakan Gatekeeper Layers sebelum masuk ke Neural Network:

1. 1.Anti-Cheat: Jika durasi belajar < 2 menit/materi, user ditandai sebagai Anomaly.
2. 2.Newcomer: Jika materi selesai < 5, user ditandai sebagai Newcomer (AI belum aktif).
3. 3.AI Classification: Mengklasifikasikan user ke:
4. 4.Fast Learner: Cepat tapi perlu dicek pemahamannya.
5. 5.Consistent Learner: Stabil dan disiplin.
6. 6.Reflective Learner: Lambat tapi mendalam (teliti).

Capstone Project A25-CS242