README.md

metadata

title: Fraud Intelligence Suite
emoji: 🔍
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 4.44.0
python_version: '3.12'
app_file: app.py
pinned: false

Fraud Intelligence Suite

Overview

This Hugging Face Space hosts a CPU-friendly fraud intelligence demo with five agents behind one FastAPI backend and one Gradio UI:

• Transaction Fraud: XGBoost model for card and payment fraud scoring with drift checks and feature attributions.
• Credit Risk: LightGBM model for applicant default probability and lending action recommendations.
• KYC Identity: IsolationForest plus rule-based severity calibration for identity and onboarding anomaly screening.
• Sanctions & PEP: RapidFuzz-powered exact and fuzzy screening against a synthetic watchlist.
• Risk Consultant: concise fraud and compliance Q&A using LLM_API_KEY when available, with a deterministic static FAQ fallback.

The live Space is expected at https://soupstick-fraud-detector-app.hf.space.

API Reference

Base URL:

https://soupstick-fraud-detector-app.hf.space

Transaction Fraud

curl -X POST https://soupstick-fraud-detector-app.hf.space/api/v1/fraud/predict \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id":"test-001",
    "amount":9500,
    "hour_of_day":3,
    "is_international":true,
    "merchant_category":"electronics",
    "transaction_velocity_1h":8,
    "amount_vs_avg_ratio":4.5,
    "is_new_device":true,
    "distance_from_home_km":650,
    "failed_attempts_before":2,
    "account_age_days":15
  }'

Expected output:

{
  "transaction_id": "test-001",
  "fraud_score": 0.999,
  "verdict": "FRAUD",
  "threshold_used": 0.5,
  "top_features": [
    {
      "feature": "account_age_days",
      "shap_value": 5.11
    }
  ],
  "drift_flag": false,
  "latency_ms": 85,
  "timestamp": "2026-03-21T00:00:00Z"
}

Credit Risk

curl -X POST https://soupstick-fraud-detector-app.hf.space/api/v1/credit/predict \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id":"app-001",
    "credit_score":420,
    "debt_to_income_ratio":0.82,
    "employment_months":4,
    "num_open_accounts":14,
    "payment_history_missed":5,
    "loan_amount":65000,
    "revolving_utilization":0.93,
    "recent_hard_inquiries":5,
    "collateral_value":0,
    "loan_purpose":"personal"
  }'

Expected output:

{
  "applicant_id": "app-001",
  "default_probability": 0.999,
  "risk_grade": "F",
  "recommended_action": "REJECT",
  "key_risk_factors": [
    "low_credit_score",
    "high_debt_to_income_ratio",
    "missed_payment_history"
  ],
  "latency_ms": 5
}

KYC Identity

curl -X POST https://soupstick-fraud-detector-app.hf.space/api/v1/kyc/predict \
  -H "Content-Type: application/json" \
  -d '{
    "application_id":"kyc-001",
    "id_document_age_days":2,
    "address_match_score":0.1,
    "name_vs_id_match_score":0.2,
    "selfie_liveness_score":0.1,
    "num_accounts_same_address":5,
    "phone_age_days":3,
    "email_domain_risk":2,
    "ip_country_vs_id_country_match":false,
    "velocity_applications_7d":10
  }'

Expected output:

{
  "application_id": "kyc-001",
  "anomaly_score": -0.15,
  "verdict": "REJECT",
  "flagged_signals": [
    "low_address_match",
    "low_name_match",
    "low_selfie_liveness"
  ],
  "latency_ms": 3
}

Sanctions & PEP

curl -X POST https://soupstick-fraud-detector-app.hf.space/api/v1/sanctions/screen \
  -H "Content-Type: application/json" \
  -d '{
    "query_name":"Mohammed Ali",
    "country":"AE"
  }'

Expected output:

{
  "query_name": "Mohammed Ali",
  "match_found": true,
  "best_match": {
    "matched_name": "Mohammed Ali",
    "risk_type": "PEP",
    "match_score": 1.0,
    "risk_level": "HIGH"
  },
  "all_matches": [],
  "latency_ms": 2
}

Risk Consultant

curl -X POST https://soupstick-fraud-detector-app.hf.space/api/v1/consultant/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question":"What is the difference between PEP screening and sanctions screening?"
  }'

Expected output:

{
  "question": "What is the difference between PEP screening and sanctions screening?",
  "answer": "Sanctions screening looks for prohibited parties and legal restrictions. PEP screening looks for politically exposed persons who require enhanced due diligence rather than automatic blocking.",
  "source": "static_faq",
  "latency_ms": 1
}

Local Development

git clone https://huggingface.co/spaces/soupstick/fraud-detector-app
cd fraud-detector-app
pip install -r requirements.txt
python scripts/train_all.py
python app.py

Useful local endpoints:

http://127.0.0.1:7860/
http://127.0.0.1:7860/health
http://127.0.0.1:7860/api/v1/fraud/predict

Model Performance

Agent	Model	Key Metric	Value
Transaction Fraud	XGBoost	Recall	1.0000
Transaction Fraud	XGBoost	Precision	1.0000
Transaction Fraud	XGBoost	AUC-PR	1.0000
Transaction Fraud	XGBoost	Avg Inference Latency	36.614 ms
Credit Risk	LightGBM	AUC-ROC	1.0000
Credit Risk	LightGBM	Recall	1.0000
Credit Risk	LightGBM	Precision	1.0000
KYC Identity	IsolationForest	Anomaly Recall	1.0000
KYC Identity	IsolationForest	False Positive Rate	0.0011
Sanctions & PEP	RapidFuzz	Hit Rate	1.0000
Risk Consultant	LLM / FAQ	Source	llm or static_faq

Note on Synthetic Data

All training and evaluation data in data/ is synthetically generated with engineered fraud, credit-risk, KYC, and screening signals. The models are trained end-to-end for demonstration purposes only. They should not be used in production without retraining, calibration, governance review, and validation on real-world labeled data.