---
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.

![HF Space](https://img.shields.io/badge/🤗%20HuggingFace-Live%20Demo-yellow?style=flat-square)
![Python](https://img.shields.io/badge/Python-3.11-blue?style=flat-square)
![FastAPI](https://img.shields.io/badge/FastAPI-0.111-green?style=flat-square)
![License](https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square)

**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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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](https://github.com/Souptik96/riskos-fraud-intelligence) (this repo) | Scoring + detection |
| Risk Pipeline | [riskos-risk-pipeline](https://github.com/Souptik96/riskos-risk-pipeline) | Rule engine + triage |
| LLM Guard | [riskos-llm-guard](https://github.com/Souptik96/riskos-llm-guard) | Output safety |
| Marketplace Intelligence | [riskos-marketplace-intelligence](https://github.com/Souptik96/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.