🔎 Suspicious money often looks normal one transfer at a time. VEXORA rebuilds the journey of the funds as a time-ordered graph, detects fraud patterns live on IBM LinuxONE, explains every case with evidence, and keeps the model, the evidence and the run in IBM Cloud.
⚖️ Disclaimer: VEXORA is an investigation-support prototype built on synthetic data only. It ranks transfers and builds cases for a human investigator; it never decides that something is money laundering. Its evidence package is an FIU-oriented investigation-support package, not an official FIU filing.
🎥 Demo • 🚀 Quick Start • 🏗️ Architecture • 📸 Screenshots • 🔭 Future • 👥 Team
🎥 Watch the Demo
▶️ Click to watch the demo on YouTube (3 min)
Live transfers → 8 fraud patterns in one case → explanation and evidence → IBM Cloud (watsonx.ai Runtime, Object Storage, watsonx.governance)
🏆 Why VEXORA?
Transaction-by-transaction monitoring → each transfer looks normal; the journey of the money is invisible
VEXORA → temporal fund-flow graph, 9 fraud patterns, ML model, evidence per case
🌟 Project Overview
VEXORA (code name FlowGuard) follows money as it moves between accounts, products, branches and channels inside one
bank, and turns each potentially suspicious flow into one case an investigator can read in seconds. A machine-learning
model ranks the transfers worth a look; a temporal fund-flow graph follows the money before and after each one and
explains what happened, why it is potentially suspicious, where the money came from and where it went. The investigator
makes the decision.
🎓 Academic Supervisor: Dr. Karthika R.N, Assistant Professor, Saveetha Engineering College
📅 Academic Year: to be added
🏛️ Institution: Saveetha Engineering College, Chennai
🎯 Problem Statement
Suspicious financial activity hides in the journey of funds: one transfer looks normal, but the chain of transfers
across accounts, products, branches and channels does not. Tools that score each transfer alone cannot see that
journey. VEXORA rebuilds it as a temporal graph, detects layering, round-tripping, structuring-like splitting,
dormant-account activation, customer-profile mismatch, fan-in, fan-out and pass-through patterns, scores every transfer
with a graph-feature ML model, and gives the investigator a traceable evidence package for each case.
✨ Feature Highlights
- Every transfer is validated, scored and placed on the fund-flow graph as it arrives (multi-notebook live simulation)
- Event gate rejects malformed or duplicate transfers into a quarantine
- Live case building: one case grows as new transfers join (risk 82 → 93 → 97 in the demo sequence, M81)
- Transaction network with replay, escalations, case queue and an investigator case panel
- Per-transfer latency measured on LinuxONE (p50 86 ms, p95 124 ms for ordinary transfers under load, M64)
- Causal graph features: each value uses only the transaction itself and earlier ones (checked in
04_graph)
- Forward and backward fund tracing along time-respecting paths, with hop, time, amount, channel and product filters
- Detectors: layering, round-tripping, structuring-like, dormant activation, profile mismatch, fan-in, fan-out,
pass-through, plus mixed typology (several in one case)
- Every pattern hit cites the exact transactions behind it
- IBM Snap ML Graph Feature Preprocessor + behaviour features → XGBoost (186 features)
- Chronological train / validation / test split with a leakage guard
- Synthetic bank test: PR-AUC 0.749 (graph + ML) vs 0.270 (transaction-only ML) vs 0.026 (rules) (M48)
- IBM public AML dataset HI-Small: PR-AUC 0.0325, recall 36.2% within a 1% alert budget (M44)
- Retraining on LinuxONE reproduces the deployed model byte for byte (M80)
- Why flagged, with evidence transaction ids for every reason
- Model's own reasons (TreeSHAP) and what the model contributes
- Risk as it unfolded and what-if: risk without each signal
- Investigator copilot answers from the case's own evidence; verdicts and dispositions are recorded in an audit log
- Evidence package (JSON + PDF) with masked identifiers and a fact-validated narrative
- watsonx.ai Runtime (IBM Cloud Pak for Data): the live model is deployed as an online deployment; every transfer
scored on LinuxONE is re-scored in IBM Cloud with identical results (200/200 test rows, M78; live 9/9)
- IBM Cloud Object Storage: every exported evidence package is archived with its SHA-256, read back and checked
(M79)
- watsonx.governance: the model's record, its lifecycle (Validate → Operate during a live run) and each run's counts
(M69, M70)
- watsonx.ai (Granite) narrative adapter: built and integrated earlier (M35–M37, M60), with a visible fallback to a
labelled template; not live in the current demo (Lite token quota used up)
- Proofs run from the LinuxONE terminal:
scripts/ibm_proof.py runtime and scripts/ibm_proof.py cos print MATCH
- The whole pipeline runs in Jupyter on IBM LinuxONE (s390x, big-endian)
- Telum on-chip AI accelerator: Snap ML reports the zDNN path for the model (
accelerator_use_reported_by_library: true, M63)
- Resource-aware: the monitor with the model uses about 0.5 GB (M67)
- Synthetic data only; account and customer identifiers are masked in evidence
- Credentials only in
.env (never committed; .env.example has placeholders)
- Every number has a claim id (
M##) in docs/CLAIM_REGISTER.md; every decision a D## in
docs/DECISION_LOG.md
- IBM integrations labelled honestly: PLANNED / MOCKED / CONFIGURED / INTEGRATED / VALIDATED
🏗️ Architecture
End-to-end: transaction generator → event bus → event gate → streaming engine → typology detectors → risk engine →
monitor, with the live model scorer on IBM LinuxONE; the IBM link logs the run to watsonx.governance, re-scores in
watsonx.ai Runtime and archives evidence in Object Storage.
🧩 System Components
| Component | File | Technology | Purpose |
|---|
| Live Monitor | flowguard/monitor_app.py, notebooks/sim/01_monitor.ipynb | Python, Jupyter, JavaScript | Scores every transfer on arrival, cases, case panel |
| Transaction Generator | flowguard/generator_app.py, notebooks/sim/00_generator.ipynb | Python | 21 scripted AML scenarios and hard negatives |
| Event Bus | flowguard/bus.py | SQLite WAL | Shared stream between notebooks, replayable |
| Temporal Graph | flowguard/graph.py, flowguard/temporal.py | NetworkX, pandas | Causal features, forward / backward tracing |
| Typology Detectors | flowguard/typologies.py | Python | 9 fraud patterns with cited evidence |
| Risk Engine | flowguard/risk.py | Python | Cases, inspectable risk components, decisions |
| Live Model Scorer | flowguard/live_model.py | IBM Snap ML GFP + XGBoost | Per-transfer ML score and explanation |
| Evidence & Investigation | flowguard/evidence.py, flowguard/investigation.py | matplotlib, JSON | Evidence package, narrative validation, audit log |
| IBM Link | scripts/governance_live_sync.py | REST (IBM Cloud) | Governance record, Runtime re-scoring, evidence archive |
| IBM Providers | flowguard/ibm/ | Provider interfaces | watsonx.ai, governance, data adapters with visible fallback |
| IBM Proofs | scripts/ibm_proof.py | REST (IBM Cloud) | LinuxONE vs IBM Cloud comparison (MATCH) |
🔄 Request Processing Flow
Transfer published (generator / participant notebooks)
│
▼
Event Bus (SQLite WAL) ──► Event Gate (validate + quarantine)
│
▼
Streaming Engine (ledger + time windows) ──► Temporal Graph (trace forward / back)
│
├──► Live Model Scorer (Snap ML GFP + XGBoost) ── model score
│
▼
Typology Detectors (9 patterns) ──► Risk Engine (cases + decisions)
│
▼
Monitor Dashboard (flow graph + case panel) ──► Evidence Package (JSON + PDF)
│
▼
IBM Link (runs on LinuxONE)
├──► watsonx.governance (model in Operate + run counts)
├──► watsonx.ai Runtime (same model re-scores every transfer)
└──► Cloud Object Storage (evidence archived with SHA-256)
📸 Sample Results & Screenshots
🎛️ Live Monitoring
| Live Monitor | Transaction Generator |
|---|
| |
| Composite Scenario Network | Investigator Control Room |
|---|
| |
🔍 Case Investigation
| Case Story | Why Flagged & What-If |
|---|
| |
| Investigator Copilot | Evidence Export |
|---|
| |
☁️ IBM Cloud Integration
| watsonx.ai Runtime: Deployment | watsonx.ai Runtime: Predict |
|---|
| |
| watsonx.governance: Operate | watsonx.governance: Live Run Record |
|---|
| |
| Cloud Object Storage: Evidence Archive | LinuxONE vs IBM Runtime Scores |
|---|
| |
📊 Training & Evaluation Metrics
| PR Curves | Confusion Matrices |
|---|
| |
| Recall by Fraud Pattern | Caught Patterns Graph |
|---|
| |
Screenshots from the LinuxONE runs (some show the code name FlowGuard). All data is synthetic.
📂 Project Structure
Explainable-Fund-Flow-Tracing-for-Fraud-Detection/
│
├── 📁 flowguard/ # The Python package (all logic)
│ ├── data.py · validation.py # Data contract, validation
│ ├── graph.py · temporal.py # Temporal fund-flow graph, tracing
│ ├── typologies.py # 9 fraud-pattern detectors
│ ├── risk.py # Risk engine: cases, decisions
│ ├── evidence.py · investigation.py # Evidence package, audit log
│ ├── live_model.py # Live ML scorer (Snap ML GFP + XGBoost)
│ ├── monitor_app.py · generator_app.py # Live simulation apps
│ ├── 📁 ibm/ # IBM provider interfaces and adapters
│ └── 📁 web/ # Monitor, generator, case panel UI
│
├── 📁 notebooks/ # Orchestration and demonstration
│ ├── 01_environment · 02_data · 04_graph · 07_risk · 08_investigation · 10_ibm
│ ├── FLOWGUARD_DEMO.ipynb · FLOWGUARD_LIVE.ipynb
│ └── 📁 sim/ # Live simulation: monitor, generator, participants
│
├── 📁 scripts/ # IBM link, IBM proofs, deploy, LinuxONE helpers, QA
│ ├── governance_live_sync.py # IBM link (governance, Runtime, Object Storage)
│ ├── ibm_proof.py # LinuxONE vs IBM Cloud proofs
│ ├── deploy_ibm_runtime.py # Model deployment to watsonx.ai Runtime
│ ├── ibm_cos_archive.py # Evidence archive in Object Storage
│ └── prerun_notebooks.py # Run all notebooks on LinuxONE
│
├── 📁 tests/ # Unit and integration tests
├── 📁 docs/ # Decisions, claims, guides, reports
│ ├── TECHNICAL_README.md # Full technical detail
│ ├── VIDEO_PRESENTATION_GUIDE.md # Demo run steps
│ ├── CLAIM_REGISTER.md · DECISION_LOG.md
│ ├── 📁 img/ · 📁 report/ # Images and screenshots
│ └── 📁 judge/ # One-page judge view
│
├── 📄 config.yaml · requirements.txt · .env.example
├── 📄 LICENSE
└── 📄 README.md
🛠️ Tech Stack
| Category | Technologies |
|---|
| AI / ML | XGBoost · IBM Snap ML (Graph Feature Preprocessor) · scikit-learn · Keras (baseline) · NumPy · pandas |
| Explainability | TreeSHAP model reasons · what-if analysis · evidence-cited reasons |
| Graph | NetworkX · temporal causal graph features |
| Runtime | IBM LinuxONE (s390x) · Jupyter · Python 3.12 · IBM zDNN (Telum) |
| Frontend | HTML5 · CSS3 · JavaScript (in-notebook apps) |
| IBM Cloud | watsonx.ai Runtime · Cloud Object Storage · watsonx.governance · watsonx.ai (Granite adapter) |
| Data | Synthetic bank (267,860 tx) · IBM HI-Small public AML dataset · SQLite event bus |
| Quality | pytest (543 passed) · ruff · mypy · bandit · radon (scripts/qa.py) |
📦 Installation & Setup
📋 Prerequisites
✓ Python 3.10+ (3.12 on LinuxONE) ✓ IBM Cloud account (Lite plans)
✓ Git ✓ IBM LinuxONE Jupyter (for Snap ML GFP)
1️⃣ Clone
git clone https://github.com/ShivrajRajasekaran/Explainable-Fund-Flow-Tracing-for-Fraud-Detection.git
cd Explainable-Fund-Flow-Tracing-for-Fraud-Detection
2️⃣ Virtual Environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
On a fresh LinuxONE VM: bash scripts/setup_linuxone_fresh.sh (creates /opt/flowguard-venv).
3️⃣ Configure IBM Cloud Credentials
Copy .env.example to .env (never commit it):
# watsonx.governance, watsonx.ai Runtime and Cloud Object Storage (one IBM Cloud account)
IBM_GOVERNANCE_API_KEY=your_api_key_here
# watsonx.ai narrative (optional)
IBM_API_KEY=your_api_key_here
IBM_PROJECT_ID=your_project_id
IBM_URL=https://us-south.ml.cloud.ibm.com
IBM_MODEL_ID=ibm/granite-4-h-small
4️⃣ Run
python scripts/prerun_notebooks.py --with-training # runs every notebook and saves its outputs
Then open notebooks/sim/01_monitor.ipynb and notebooks/sim/00_generator.ipynb in JupyterLab.
🚀 Quick Start
1️⃣ Monitor → notebooks/sim/01_monitor.ipynb (Restart Kernel and Run All)
2️⃣ Generator → notebooks/sim/00_generator.ipynb (Run All; interval 2 s; Composite)
3️⃣ IBM link → python -u scripts/governance_live_sync.py live --local
4️⃣ Play → Composite → Dormant activation → Structuring: 8 patterns in one case
5️⃣ Evidence → Export evidence (JSON + PDF) → archived in IBM Cloud Object Storage
6️⃣ Proofs → python scripts/ibm_proof.py runtime · python scripts/ibm_proof.py cos
Full click-by-click steps: docs/VIDEO_PRESENTATION_GUIDE.md.
(Optional) Retrain the Model
# on LinuxONE, safe demo copy (writes to a separate folder; the live model is never overwritten)
python scripts/prerun_notebooks.py --with-training
# Output: /root/flowguard_outputs/FGSYN_demo/FGSYN/ (model, results.json, 9 charts)
📖 API Reference
VEXORA has no REST API of its own: it runs as Jupyter notebooks and command-line scripts on IBM LinuxONE.
Command reference:
| Command | Purpose | Where |
|---|
scripts/governance_live_sync.py status | Show the model's stage and run record in watsonx.governance | LinuxONE terminal |
scripts/governance_live_sync.py stage validate | Put the model back in Validate | LinuxONE terminal |
scripts/governance_live_sync.py live --local | IBM link during a live run | LinuxONE terminal |
scripts/ibm_proof.py runtime | LinuxONE vs watsonx.ai Runtime, same input | LinuxONE terminal |
scripts/ibm_proof.py cos | Object Storage contents, SHA-256 checked | LinuxONE terminal |
scripts/deploy_ibm_runtime.py --status | Read the Runtime deployment back from IBM | Laptop |
scripts/prerun_notebooks.py | Run and save every presentation notebook | LinuxONE terminal |
scripts/qa.py | Quality gate (lint, types, security, tests) | Laptop |
📊 Model Performance
| Metric | Value |
|---|
| Architecture | IBM Snap ML Graph Feature Preprocessor + XGBoost (186 features) |
| Detection design | Model-led: the model opens cases; graph and patterns explain them (D41) |
| Synthetic bank, test PR-AUC | rules 0.026 · transaction-only ML 0.270 · graph + ML 0.749 (M48) |
| IBM HI-Small, test PR-AUC | rules 0.0007 · transaction-only ML 0.0186 · graph + ML 0.0325, recall 36.2% at a 1% budget (M44) |
| Live sequence | 8 fraud patterns in one case, risk 82 → 93 → 97 (M81) |
| Latency on LinuxONE | p50 86 ms, p95 124 ms per ordinary transfer, under load (M64) |
| IBM Cloud parity | 200/200 identical alert decisions, score difference 0 (M78) |
The synthetic bank is much easier than IBM's data; judge detection by the IBM numbers. Full results and limits:
docs/TECHNICAL_README.md.
🔭 Future Developments
VEXORA's next stage moves from suspicious-transaction detection towards evidence-grounded financial investigation.
Each direction builds on something that already works today (claim ids in docs/CLAIM_REGISTER.md).
These are proposed extensions, not implemented capabilities.
| # | Direction | What exists today | Next step | How we will measure it |
|---|
| 1 | Counterfactual fund-flow investigation | What-if: risk without each signal in every case; forward / backward re-tracing with hop, time, amount and channel controls | Drop or alter single transfers, rank alternative paths, and show how the case risk would change, labelled as analytical scenarios, not proof | Stability of the case ranking; investigator agreement on the key transfers |
| 2 | Adaptive laundering-pattern discovery | Model-led cases catch a round-trip type the model never saw in training (70.4% recall, M55); typology-confidence novelty signal (AUC 0.758, M58) | Temporal graph motif mining and anomaly scores to surface new shapes for analyst review | Cases found that rules and the model missed, confirmed by an analyst |
| 3 | Evidence-verified watsonx.ai narratives at scale | Every narrative is checked against the case facts: invented ids, amounts, dates, unmasked identifiers and legal conclusions are rejected (0 unsupported items, M36, M60) | Run the check over many cases, with adversarial tests that hide or alter evidence | Share of claims with valid supporting transaction ids; detected unsupported claims |
| 4 | Telum AI accelerator as the live scorer | IBM Snap ML scores our model through IBM zDNN on LinuxONE (M63); the live detector stays XGBoost because missing values are handled differently | Retrain with explicit missing-value handling so the accelerated model equals the detector | Score parity with XGBoost; per-transfer latency |
| 5 | Real-time scale on IBM Z | p50 86 ms per ordinary transfer under load (M64); about 0.5 GB for the monitor with the model (M67) | Stream from an enterprise message queue and scale across more cores and transaction volume | Throughput; p95 / p99 latency; memory |
| 6 | Robustness and generalisation | Chronological splits with a leakage guard; IBM HI-Small benchmark (M44); time-of-day sensitivity measured (M61) | More time windows, IBM's LI datasets, per-pattern error analysis, removing the time-of-day bias | PR-AUC; recall and precision within a 1% alert budget; false-positive workload |
| 7 | Continuous model governance |
Research principle: each extension needs a reproducible evaluation, a comparison against today's baseline and
documented limits before it is called validated.
🔒 Security Checklist
⚠️ VEXORA is a prototype. Any production use would need the bank's data governance, regulatory review and validation on
real data.
👥 Authors & Contributors
🏆 Team BIG IRON 2.0 — IBM Z Datathon 2026
🎓 Academic Guidance
| Role | Name | Institution |
|---|
| Academic Supervisor | Dr. Karthika R.N, Assistant Professor | Saveetha Engineering College |
🤝 Contributing
Contributions are welcome. By submitting a pull request you agree that your contribution is released under the
project's MIT license.
How to Contribute
- Open an Issue: discuss your idea before coding
- Fork the repository
- Create a branch:
git checkout -b feature/YourFeature
- Commit:
git commit -m 'feat: Add YourFeature'
- Open a Pull Request with a detailed description, and run
python scripts/qa.py first
Contribution Areas
| Area | Difficulty | Skills Needed |
|---|
| 🕸️ New fraud-pattern detectors | Advanced | Python, graph analytics, AML |
| 🧠 Model improvements | Advanced | XGBoost, Snap ML, feature engineering |
| ☁️ IBM Cloud integrations | Medium | IBM Cloud APIs |
| 🎨 Monitor and case-panel UI | Medium | HTML, CSS, JavaScript |
| 🧪 Tests and validation | Medium | pytest |
| 📚 Documentation | Beginner | Markdown |
📄 License
╔══════════════════════════════════════════════════════════════════╗
║ MIT LICENSE ║
║ Copyright (c) 2026 ShivrajRajasekaran ║
╚══════════════════════════════════════════════════════════════════╝
This project is released under the MIT License: see LICENSE. The ML model code is Vikamuhan N's work;
see docs/TECHNICAL_README.md for what is in this repository.
Licensing questions: @ShivrajRajasekaran via GitHub Issues
🙏 Acknowledgments
| Contribution | Name / Organization |
|---|
| Runtime | IBM LinuxONE: s390x Jupyter environment, Telum on-chip AI accelerator |
| Cloud Services | IBM Cloud: watsonx.ai Runtime, Cloud Object Storage, watsonx.governance, watsonx.ai |
| Graph Features | IBM Snap ML: Graph Feature Preprocessor |
| Dataset | IBM: public synthetic AML dataset (HI-Small) |
| ML | XGBoost, scikit-learn, Keras |
| Competition Platform | IBM Z Datathon 2026: organizer to be added |
| Guidance | Dr. Karthika R.N, Assistant Professor, Saveetha Engineering College |
| Institution | Saveetha Engineering College, Chennai |
⭐ Star this repository if VEXORA helped your project!
Made for following the money, transparently
IBM Z Datathon 2026 · Problem Statement 9 · India 🇮🇳
🐛 Report Bug · 💡 Request Feature · 📖 Technical README · 🎥 Demo
