FrauDect

Fraud-risk scoring và hỗ trợ xếp hạng giao dịch cho manual review trên Sparkov synthetic dataset.

FrauDect gồm workflow Data Scientist đã khóa và lớp Machine Learning Engineering raw-to-prediction dùng chung cho CLI, API và dashboard. Model không tự động từ chối giao dịch hoặc khóa thẻ.

Dashboard governance được chụp từ ứng dụng Streamlit chạy thật cùng production artifact:

Kết quả locked holdout

Model cuối là XGBoost không class weighting, được chọn bằng temporal validation và blocked temporal cross-validation. Isotonic calibrator và threshold 0,0200 được khóa trước khi mở fraudTest.csv.

Metric	Validation	Locked holdout
Average Precision	0,8784	0,8259
Recall	0,9426	0,9254
Precision	0,3681	0,2758
F2	0,7184	0,6291
Brier score	0,001533	0,001302
Recall tại review budget 1%	90,82%	89,88%

Locked holdout gồm 555.719 transaction và 2.145 fraud. Kết quả được ghi tại reports/ds/06_holdout_report.json. Holdout evaluation count được khóa ở 1; notebook 06 có guard ngăn chạy lại.

Những kết luận thay đổi sau khi chạy dữ liệu thật

• log_amt, category và hour là các signal chính của model.
• log_distance_km không phải feature mạnh: univariate AP khoảng 0,0060 và permutation importance khoảng -0,0033. Tuyên bố cũ “distance là feature mạnh nhất” bị bác bỏ.
• Logistic Regression không resampling đạt AP 0,3692, cao hơn nhiều so với class weight, SMOTE và undersampling trong temporal validation.
• Weighted variants không thắng unweighted variants về ranking trong ba họ tree.
• XGBoost unweighted đạt blocked temporal CV AP trung bình 0,8322, độ lệch chuẩn 0,0183.
• Holdout AP thấp hơn validation 0,0525; đây là generalization gap, không được dùng để tune lại model.

Workflow Data Scientist

Chạy và đọc theo đúng thứ tự:

1. 01_EDA.ipynb: business framing, data quality, imbalance, temporal drift và entity overlap.
2. 02_Feature_Engineering.ipynb: feature contract, leakage, multicollinearity và stability.
3. 03_Imbalance_Strategies.ipynb: no-resampling, class weight, undersampling và SMOTE.
4. 04_Model_Experiments.ipynb: bảy model candidates, MLflow, calibration, threshold và temporal CV.
5. 05_Model_Interpretation.ipynb: permutation importance, SHAP, local explanation và segment errors.
6. 06_Business_Report.ipynb: locked holdout, generalization, review capacity, cost sensitivity và giới hạn sử dụng.

Data protocol

fraudTrain.csv được chia theo timestamp:

Partition	Số dòng	Khoảng thời gian	Fraud rate
Development	907.672	2019-01-01 đến 2019-12-28	0,5642%
Calibration	194.501	2019-12-28 đến 2020-04-03	0,6437%
Validation	194.502	2020-04-03 đến 2020-06-21	0,5825%

Calibration được chia tiếp thành cửa sổ fit isotonic calibrator và cửa sổ khóa threshold. fraudTest.csv chỉ được đọc tại notebook 06.

Feature policy

• Production candidates: amount, distance, population ratio, age, hour, weekday, night/weekend, category và state.
• city_pop raw bị loại do Spearman 1,0 với log_city_pop.
• gender chỉ dùng error/fairness audit.
• cc_num, trans_num, tên, địa chỉ và các ID không được đưa vào model.
• state được giữ có điều kiện và cần monitoring vì có thể đóng vai trò proxy.

Workflow Machine Learning Engineer

Production bundle dùng model XGBoost unweighted, isotonic calibrator và threshold 0,02 được promote trực tiếp từ notebook 04. Bundle có SHA-256, model/schema version, feature contract, dependency version, threshold provenance và reference distribution cho monitoring.

• src/fraudect/: data contract, feature engineering, training, artifact, inference và monitoring.
• scripts/promote_ds_artifact.py: promote artifact DS mà không fit lại model.
• scripts/train.py: tái huấn luyện theo temporal protocol, không có code đọc locked holdout.
• scripts/predict.py: batch inference từ raw CSV.
• api/: FastAPI với /live, /ready, /health, /model, /predict và /predict/batch.
• frontend/: dashboard Streamlit cho fraud analyst.
• docker-compose.yml: tách API và frontend, artifact được mount read-only.
• docs/MLE_PLAN.md: kế hoạch, trạng thái và evidence của từng quality gate.
• docs/OPERATIONS.md: runbook huấn luyện, promote, serving và monitoring.

Full retraining candidate tái tạo đúng threshold và confusion matrix validation của notebook. AP của candidate là 0,8755, thấp hơn artifact notebook khoảng 0,003 do các mức hòa của isotonic calibration; vì vậy production vẫn dùng artifact đã promote. Prediction parity giữa artifact nguồn và production bundle bằng tuyệt đối trên 500 giao dịch development.

Giới hạn

• Dataset là synthetic; metric không chứng minh hiệu quả trên fraud thực tế.
• Cost FP=10 và FN=500 chỉ là sensitivity scenario, không phải dữ liệu tài chính đã xác nhận. Project không công bố ROI.
• Holdout recall thấp ở một số category, đặc biệt travel.
• Recall theo gender trên holdout khác nhau: khoảng 89,69% cho F và 95,92% cho M. Không được suy rộng thành kết luận fairness ngoài dataset này.
• Model phù hợp để xếp hạng/manual review, không phù hợp để tự động decline.

Thiết lập môi trường

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev,api,frontend,notebooks]"

Mở notebook:

.venv\Scripts\python.exe -m jupyter lab notebooks

Audit notebook mà không chạy lại holdout:

.venv\Scripts\python.exe scripts\audit_notebooks.py

Không chạy lại 06_Business_Report.ipynb sau khi reports/ds/06_holdout_report.json đã tồn tại.

Quick start serving

Promote và kiểm tra artifact đã khóa:

.venv\Scripts\python.exe scripts\promote_ds_artifact.py
.venv\Scripts\python.exe scripts\check_artifact.py

Chạy API và dashboard ở hai terminal:

.venv\Scripts\python.exe -m uvicorn api.app.main:app --port 8000
.venv\Scripts\python.exe -m streamlit run frontend/app.py

Hoặc dùng Docker Compose sau khi đã có artifacts/fraudect.joblib:

docker compose up --build

Compose mặc định mở API tại http://localhost:8001 và dashboard tại http://localhost:8503 để tránh xung đột với các service local thường dùng cổng 8000/8501. Có thể ghi đè bằng FRAUDECT_API_PORT và FRAUDECT_FRONTEND_PORT.

Quality gates local:

.venv\Scripts\python.exe -m ruff check src/fraudect api scripts tests
.venv\Scripts\python.exe -m pytest
.venv\Scripts\python.exe -m compileall -q src/fraudect api scripts
.venv\Scripts\python.exe -m pip check