tools/README.md

# 🔧 Tools Directory

Folder ini berisi model machine learning dan konfigurasi untuk anomali detection.

---

## 📦 Files Required

```
tools/
├── scaler.pkl              ← StandardScaler model (binary)
├── isolation_forest.pkl    ← Isolation Forest model (binary)
├── metadata.json           ← Configuration
├── model_train.py          ← Training script (optional)
└── simpanan_analisis.py    ← Helper functions (optional)
```

---

## 📋 File Descriptions

### scaler.pkl

- **Type:** Binary (Pickle format)
- **Purpose:** Standardize features untuk ML model
- **Used by:** Tab 2 (Analisa Simpanan)
- **Size:** ~1-2 KB

### isolation_forest.pkl

- **Type:** Binary (Pickle format)
- **Purpose:** Pre-trained Isolation Forest model untuk anomali detection
- **Used by:** Tab 2 (Analisa Simpanan)
- **Features:** 8 fitur (Db_Sukarela dan Cr_Sukarela aggregates)
- **Size:** ~10-50 KB

### metadata.json

- **Type:** JSON (Text)
- **Purpose:** Konfigurasi model dan parameter
- **Content:**
  ```json
  {
    "feature_cols": [...],           // Nama kolom untuk model
    "rolling_zscore_threshold": 1.0, // Threshold untuk Z-Score
    "rolling_window": 3              // Window size untuk rolling aggregation
  }
  ```

### model_train.py (Optional)

Script untuk melatih ulang model jika diperlukan.

### simpanan_analisis.py (Optional)

Helper functions untuk analisa simpanan.

---

## ⚠️ Important Notes

### Binary Model Files (.pkl)

- File `scaler.pkl` dan `isolation_forest.pkl` HARUS ada untuk Tab 2 berfungsi
- Files ini di-generate saat training, bukan di-create manual
- Jangan di-edit manual - format binary

### File Locations

- App mencari file di path relatif: `../tools/` (dari app folder)
- Pastikan struktur folder sesuai template

### Model Updates

Jika ingin update model (retrain):

1. Jalankan `python tools/model_train.py`
2. File `.pkl` baru akan di-generate
3. Restart aplikasi

---

## 🔍 Troubleshooting

### Error: "Model tidak ditemukan"

```
Solusi:
1. Pastikan scaler.pkl ada di tools/
2. Pastikan isolation_forest.pkl ada di tools/
3. Check file paths (case-sensitive di Linux/Mac)
```

### Error: "Model load failed"

```
Solusi:
1. Pastikan Python version sama saat training dan running
2. Pastikan scikit-learn version sama
3. Re-train model jika masih error
```

---

## 📊 Model Info

### Isolation Forest

- **Algorithm:** Anomaly detection via Isolation Forest
- **Training data:** Historical simpanan transactions
- **Features:** 8 aggregated metrics
  - Db_Sukarela_Total, Db_Sukarela_Avg, Db_Sukarela_Std, Db_Sukarela_Max
  - Cr_Sukarela_Total, Cr_Sukarela_Avg, Cr_Sukarela_Std, Cr_Sukarela_Max
- **Output:** Binary (Anomaly: -1, Normal: 1)

### StandardScaler

- **Purpose:** Feature normalization
- **Fitted on:** Historical data statistics
- **Usage:** Pre-process features before model prediction

---

## 🚀 Quick Check

Verify tools setup:

```bash
cd THC_APP
python -c "import joblib; print('scaler:', joblib.load('tools/scaler.pkl')); print('model:', joblib.load('tools/isolation_forest.pkl'))"
```

Success jika output menunjukkan objects tanpa error.

---

**Last Updated:** May 2026