On This Page
Documentation
How to Use
FraudShield AI
A complete guide to running predictions with each model — what each input means, what values trigger high risk, how to interpret results, and how to use the Combined Risk Engine to see all three models work together.
Overview
The 3-Model Detection Pipeline
Individual testing", desc: "Go to Model Gallery → click "Test Model" on any card → fill inputs → Run Analysis.
Combined engine
Go to Risk Engine from the navbar → fill the unified form → Run Combined Analysis.
Reading results
Every prediction returns a 0–100 risk score, SAFE/SUSPICIOUS/FRAUD verdict, reasoning text, and top factors.
Model 1 — TransactionGuard XGB+LGB
Supervised · Transaction FraudWhat it does
Asks whether THIS specific transaction is fraudulent based on its features — amount, card type, PCA velocity signals, time of day.
When to use it
Use this as your primary fraud gate. It catches known fraud patterns with the highest precision of the three models because it was trained on 20,000+ labelled fraud examples.
What Each Input Means
Transaction Amount ($)
The dollar value. Large amounts at night are high risk.
PCA Feature V1
Velocity signal from IEEE-CIS. Negative values (< -2) strongly indicate fraud.
PCA Feature V3
Merchant risk signal. Large negative values are suspicious.
Card Network
Visa and Mastercard are baseline. Discover in unusual contexts is higher risk.
Product Code
W = electronic goods (common fraud target). C = cash equivalent (high risk).
Hour (0–23)
Transactions between midnight and 5am elevate risk significantly.
Sample Test Values — Copy & Paste
| Field | Value | Why |
|---|---|---|
| Transaction Amount | 29.99 | Normal retail amount |
| V1 (Velocity) | 0.5 | Positive = lower risk |
| V3 | 0.2 | Near-zero = normal |
| Card Network | visa | Common card type |
| Product Code | W | Standard product |
| Hour | 14 | 2pm — business hours |
| Field | Value | Why |
|---|---|---|
| Transaction Amount | 8500.00 | Unusually large |
| V1 (Velocity) | -4.2 | Strongly negative |
| V3 | -3.1 | Negative = risky |
| Card Network | discover | Less common |
| Product Code | C | Cash equivalent |
| Hour | 3 | 3am — high risk window |
How to Read the Results
Combined Risk Engine
The /combined page runs all three models with a single form submission and combines their scores using weighted averaging (40%/30%/30%).
Go to the Risk Engine page
Click Risk Engine in the navbar, or go directly to /combined.
Fill the unified input form
The form has three sections — Transaction, Card & Product, and User Behaviour. Fill as many fields as you know. Empty fields default to neutral values.
Fields labelled (Models 1 & 2) affect those two models. Fields labelled (Model 3) control behavioural signals.
Click "Run Combined Analysis"
The scanning overlay runs while all three models score in sequence. This takes about 2–3 seconds.
Read the combined verdict banner
At the top: an animated gauge with the combined score (weighted average) and a LOW/MEDIUM/HIGH/CRITICAL risk level.
Below: three individual score cards — one per model — each showing score, verdict, reasoning, and top factors.
Check the Pipeline Diagram
At the bottom of the results: an animated flow diagram showing how all three scores fed into the combined verdict, with their actual numeric values and weights.
Try These Combined Scenarios
Amount
Hour
V1
V14
User Avg Amount
Min Since Last
User Avg Hour
User Txn Count
Reading Every Result
Risk Score Gauge (0–100)
0–34
SAFEAll signals within normal range. No action needed.
35–69
SUSPICIOUSBorderline signals. Consider secondary verification.
70–100
FRAUDHigh-confidence fraud/anomaly/ATO detected. Block or escalate.
Top Contributing Factors
Each factor row shows: Feature name → its value for this prediction → an ↑ up arrow (increases fraud risk) or ↓ down arrow (decreases risk).
Model 1: factors come from SHAP TreeExplainer — the exact mathematical contribution of each feature to the fraud probability for this specific transaction.
Model 2: factors are per-feature reconstruction errors — the features the Autoencoder struggled most to reconstruct, meaning they were most different from the normal distribution.
Model 3: factors describe the specific behavioral deviation signals — how much the amount deviates from the user's own baseline, how unusual the hour is for them, etc.
Reasoning Text
The reasoning block is a human-readable sentence generated by the backend from the actual model outputs — it includes the exact probability, the threshold, and which specific signals pushed the verdict. It is not a template; it changes based on the actual values you submitted.
Tips & Common Mistakes
Getting the most accurate predictions
For Model 1: the model trained on 142 features. The 6 fields in the form cover the most important ones. Filling V1 and TransactionAmt is usually enough to get meaningful results.
For Model 3: the more accurately you fill "User's Typical Amount" and "User's Usual Hour", the more realistic the behavioural deviation signal. If those match the current transaction, risk will be low.
The V features (V1, V2, V3 …)
These are PCA-transformed features from the IEEE-CIS dataset — they do not map to simple real-world quantities. Think of them as "encoded velocity/merchant/device signals." The training data documentation does not reveal what they represent.
Rule of thumb: values near 0 are normal. Extreme values (below -3 or above +3) represent outliers in the original feature space and raise risk.
Common mistake — leaving all fields blank
Empty fields default to neutral/zero values. This will almost always return a SAFE verdict because the model sees a perfectly average transaction. Always fill at least Amount and one V feature for meaningful results.
The Combined Engine vs individual models
Individual model pages are useful for understanding each model in isolation and debugging. The Combined Engine is the realistic deployment scenario — use it to see how the three models interact and cover each other's blind spots.
Scenario C in the Combined section above is the key example: Models 1 and 2 both say SAFE (normal transaction, normal statistics), but Model 3 catches it because the user is behaving out of character.
FastAPI server must be running
All predictions require the Python backend. If you see a network error, check that uvicorn main:app --reload --port 8000 is running in a separate terminal. The health check at http://localhost:8000 confirms which models are loaded.