README.md

metadata

title: AML-intelligence-suite
emoji: 🔍
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 4.44.0
python_version: '3.12'
app_file: app.py
pinned: false

🔍 AML-intelligence-suite

Multi-agent AI system for real-time fraud detection, credit risk assessment, KYC identity verification, and sanctions screening.

Live Demo: https://huggingface.co/spaces/soupstick/aml-intelligence-app API Docs: https://soupstick-aml-intelligence-app.hf.space/docs

---

What This Is

AML-intelligence-suite is a production-grade multi-agent system that detects fraudulent transactions, assesses credit risk, validates KYC identities, and screens against sanctions/PEP lists. It's designed for fintech platforms, payment processors, and financial institutions that need real-time risk assessment with sub-100ms latency.

The system uses ensemble ML models (XGBoost, LightGBM, IsolationForest) optimized for high recall and interpretable feature contributions, plus fuzzy matching for sanctions screening and an LLM-powered risk consultant for operational support.

---

Agent Overview

Agent	Model	Key Metric	Value	Endpoint
📊 Transaction Fraud	XGBoost	Recall	1.0	/api/v1/fraud/predict
💳 Credit Risk	LightGBM	AUC-ROC	1.0	/api/v1/credit/predict
🆔 KYC Identity	IsolationForest	Anomaly Recall	1.0	/api/v1/kyc/predict
🌍 Sanctions & PEP	RapidFuzz	Hit Rate	>95%	/api/v1/sanctions/screen
💬 Risk Consultant	LLM / FAQ	Latency	<2000ms	/api/v1/consultant/ask

---

Architecture

User / API Client
│
▼
FastAPI Gateway (/api/v1/*)
│
├── /fraud/predict    → XGBoost Scorer → SHAP Explainer
├── /credit/predict   → LightGBM Classifier
├── /kyc/predict      → IsolationForest Anomaly Detector
├── /sanctions/screen → RapidFuzz Name Matcher
└── /consultant/ask   → LLM (GPT-4o-mini) / Static FAQ
│
▼
Investigative Agent Orchestrator (Data Aggregation & LLM Analysis)
│
▼
Investigator Dashboard (Gradio UI - Unified View)
Hosted: HuggingFace Spaces (CPU)

---

Quick Start — API in 60 Seconds

Transaction Fraud Detection

curl -X POST https://soupstick-aml-intelligence-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 response:
{
  "transaction_id": "test-001",
  "fraud_score": 0.94,
  "verdict": "FRAUD",
  "top_features": [...],
  "drift_flag": false,
  "latency_ms": 58
}

Credit Risk Assessment

curl -X POST https://soupstick-aml-intelligence-app.hf.space/api/v1/credit/predict \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "app-001",
    "credit_score": 720,
    "debt_to_income_ratio": 0.35,
    "employment_months": 48,
    "num_open_accounts": 5,
    "payment_history_missed": 1,
    "loan_amount": 15000,
    "revolving_utilization": 0.4,
    "recent_hard_inquiries": 2,
    "collateral_value": 0,
    "loan_purpose": "auto"
  }'

# Expected response:
{
  "application_id": "app-001",
  "risk_score": 0.15,
  "risk_level": "LOW",
  "decision": "APPROVE",
  "factors": ["Low debt-to-income ratio", "Good credit score"],
  "latency_ms": 42
}

KYC Identity Verification

curl -X POST https://soupstick-aml-intelligence-app.hf.space/api/v1/kyc/predict \
  -H "Content-Type: application/json" \
  -d '{
    "kyc_id": "kyc-001",
    "id_document_age_days": 30,
    "address_match_score": 0.95,
    "name_vs_id_match_score": 0.98,
    "selfie_liveness_score": 0.92,
    "num_accounts_same_address": 1,
    "phone_age_days": 365,
    "email_domain_risk": 0.1,
    "ip_country_vs_id_country_match": true,
    "velocity_applications_7d": 1
  }'

# Expected response:
{
  "kyc_id": "kyc-001",
  "anomaly_score": 0.12,
  "verdict": "PASS",
  "risk_factors": [],
  "latency_ms": 35
}

Sanctions & PEP Screening

curl -X POST https://soupstick-aml-intelligence-app.hf.space/api/v1/sanctions/screen \
  -H "Content-Type: application/json" \
  -d '{
    "screening_id": "screen-001",
    "name": "John Smith",
    "country": "US",
    "dob": "1985-01-15"
  }'

# Expected response:
{
  "screening_id": "screen-001",
  "hits": [],
  "match_count": 0,
  "verdict": "CLEAR",
  "latency_ms": 28
}

Risk Consultant

curl -X POST https://soupstick-aml-intelligence-app.hf.space/api/v1/consultant/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is a synthetic identity fraud?"
  }'

# Expected response:
{
  "answer": "Synthetic identity fraud occurs when criminals combine real...",
  "source": "static_faq",
  "latency_ms": 15
}

---

Local Development

git clone https://github.com/Souptik96/riskos-fraud-intelligence
cd riskos-fraud-intelligence
pip install -r requirements.txt
python scripts/train_all.py        # trains all models, saves to model_artifacts/
python app.py                      # starts Gradio + FastAPI on port 7860

---

Test Results

Test Suite Results (last run: 2026-03-22)

Suite	Tests Passed
Transaction Fraud	18/18
Credit Risk	11/11
KYC Identity	10/10
Sanctions & PEP	12/12
Risk Consultant	10/10
Total	61/61 (100%)

---

Model Performance

Model Performance (trained on synthetic data, SEED=42)

Transaction Fraud XGBoost

• Recall: 1.0
• Precision: 1.0
• AUC-PR: 1.0
• Latency: ~37ms

Credit Risk LightGBM

• AUC-ROC: 1.0
• Recall: 1.0
• Precision: 1.0

KYC IsolationForest

• Anomaly Recall: 1.0
• False Positive Rate: 0.0011

---

Part of RiskOS

This repository is one component of RiskOS — an open-source AI risk intelligence platform.

Component	Repo	Role
Fraud Intelligence	riskos-fraud-intelligence (this repo)	Scoring + detection
Risk Pipeline	riskos-risk-pipeline	Rule engine + triage
LLM Guard	riskos-llm-guard	Output safety
Marketplace Intelligence	riskos-marketplace-intelligence	Analytics queries

---

License and Disclaimer

MIT License. Note that all models are trained on synthetically generated data. Not intended for production use without retraining on real labeled data.