AI-Powered Suspicious Activity Detection AML Compliance Agent

An autonomous, end-to-end Anti-Money Laundering (AML) Compliance & Anomaly Detection Agent powered by Google Gemini 2.5 Flash, LangGraph StateGraph, FastAPI, and Next.js.

The platform processes natural language queries against transaction datasets, dynamically plans and routes execution flows, runs hybrid machine learning & rule-based anomaly detection engines, and generates regulatory-grade Suspicious Activity Report (SAR) narrative explanations with real-time progress streaming.

---

🌟 Key Features

• 🧠 Dynamic Execution Routing: Intelligent LLM query parsing and state graph planning using Gemini 2.5 Flash with structured schema validation (ExecutionPlanSchema). Automatically invokes necessary tools while skipping non-essential nodes to optimize response latency.
• 📥 Multi-Source Dataset Importer: Ingest transaction data from local CSV/Parquet files, Hugging Face Hub, Kaggle API, or the built-in synthetic AML dataset generator.
• 🔄 Automated Schema Engine: Intelligent fuzzy-matching and NLP regex column standardization engine mapping arbitrary data schemas into standard AML analytical schemas.
• 🔍 Hybrid Anomaly Detection Engine: Combines Isolation Forest unsupervised machine learning models with Currency Transaction Reporting (CTR) threshold evasion rules ($8,000–$9,999 structuring windows).
• 🔌 Model Context Protocol (MCP) Server Interface: Exposes core AML analytical tools (mcp_data_loader, mcp_eda_tool, mcp_feature_engine, mcp_anomaly_detector, mcp_risk_classifier, mcp_explanation_engine) via standardized MCP protocol.
• ⚡ Real-Time SSE Event Streaming: Server-Sent Events (SSE) stream detailed step and sub-step execution progress directly to the interactive Next.js dashboard UI.
• 📊 Benchmarking & Audit Suite: Comprehensive evaluation suite measuring detection model performance (Precision@K, Recall), agent routing accuracy, SAR narrative explainability fidelity, and execution latency.

---

🏗️ System Architecture

                                +---------------------------+
                                |    Next.js 16 Web App     |
                                |  (Interactive UI & SSE)   |
                                +-------------+-------------+
                                              |
                                              v  HTTP / SSE
                                +-------------+-------------+
                                |      FastAPI Server       |
                                |      (backend/main.py)    |
                                +-------------+-------------+
                                              |
                                              v
                              +---------------+---------------+
                              |    Gemini 2.5 Flash Planner   |
                              |  (Dynamic Query Routing)      |
                              +---------------+---------------+
                                              |
                                              v
+-----------------------------------------------------------------------------------+
|                        LangGraph StateGraph Execution Pipeline                    |
|                                                                                   |
|  +------------------+     +---------------+     +--------------------+            |
|  | mcp_data_loader  | --> | mcp_eda_tool  | --> | mcp_feature_engine |            |
|  +------------------+     +---------------+     +--------------------+            |
|                                                           |                       |
|                                                           v                       |
|  +-------------------------+     +---------------------+  |                       |
|  | mcp_explanation_engine  | <-- | mcp_risk_classifier | <-+                       |
|  | (SAR Narrative Engine)  |     | (Risk Tiering 0-100)|   |                       |
|  +-------------------------+     +---------------------+   |                       |
|                                           ^                |                      |
|                                           |  (If Enabled)  v                      |
|                                           +------- +----------------------+       |
|                                                    | mcp_anomaly_detector |       |
|                                                    | (Isolation Forest/CTR)|       |
|                                                    +----------------------+       |
+-----------------------------------------------------------------------------------+

---

🛠️ Quickstart Guide

Prerequisites

• Python: >=3.11 (Python 3.11 or 3.12 recommended)
• Node.js: >=18.0.0 and npm
• Pixi Package Manager (Recommended): Install Pixi or use standard pip
• Gemini API Key: Obtain a key from Google AI Studio

1. Environment Setup

Copy .env.example to .env and set your credentials:

cp .env.example .env

Edit .env:

# Required for Gemini LLM Planner & SAR Narrative Engine
GEMINI_API_KEY="your_gemini_api_key_here"

# Optional: For Hugging Face Hub dataset downloads
HF_TOKEN="your_huggingface_token_here"

# Optional: For Kaggle API dataset imports
KAGGLE_USERNAME="your_kaggle_username"
KAGGLE_KEY="your_kaggle_api_key"

---

2. Backend Installation & Server Run

Option A: Using Pixi (Recommended)

# Install dependencies
pixi install

# Start backend FastAPI server
pixi run start

Option B: Using Pip & Virtual Environment

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt  # or install dependencies listed in pyproject.toml / pixi.toml

# Start backend server
python -m backend.main

The FastAPI backend will run on http://localhost:8000. You can inspect interactive API documentation at http://localhost:8000/docs.

---

3. Frontend Installation & Server Run

In a separate terminal window:

cd frontend

# Install Node dependencies
npm install

# Start Next.js development server
npm run dev

Open http://localhost:3000 in your web browser to interact with the AML Compliance Dashboard.

---

4. Running the MCP Tool Server

To launch the standalone Model Context Protocol (MCP) server:

pixi run python -m backend.mcp_server

---

📂 Project Directory Structure

.
├── backend/                        # Python Backend Application
│   ├── agent/                      # LangGraph & Gemini Planning Agent
│   │   ├── graph.py                # LangGraph StateGraph & SSE streaming runner
│   │   ├── planner.py              # Gemini 2.5 Flash query planner & schema parser
│   │   ├── schema_agent.py         # Automated schema transformation agent
│   │   ├── state.py                # Agent state dataclass definition
│   │   └── llm_logger.py           # LLM call tracking & audit logger
│   ├── data/                       # Data Management & Storage
│   │   ├── dataset_manager.py      # Multi-source dataset manager & schema engine
│   │   ├── generator.py            # Synthetic AML dataset generator
│   │   └── storage/                # Active dataset CSV/Parquet storage
│   ├── evaluation/                 # Evaluation & Benchmarking Suite
│   │   ├── benchmark.py            # Main full benchmark runner
│   │   ├── eval_agent.py           # Routing & tool decision benchmarks
│   │   ├── eval_explainability.py  # SAR explanation quality metrics
│   │   └── eval_models.py          # ML anomaly detection metrics
│   ├── tools/                      # Analytical MCP Tool Implementations
│   │   ├── data_loader.py          # Data filtering tool
│   │   ├── eda_tool.py             # Profiling & EDA tool
│   │   ├── feature_engine.py       # AML feature engineering tool
│   │   ├── anomaly_tool.py         # Isolation Forest & CTR anomaly detector
│   │   ├── risk_classifier.py      # Risk scoring & tiering tool
│   │   └── explanation_engine.py   # SAR explanation & escalation tool
│   ├── main.py                     # FastAPI server entry point
│   └── mcp_server.py               # Standalone MCP tool server interface
├── frontend/                       # Next.js 16 Web Dashboard
│   ├── app/                        # Next.js App Router pages
│   ├── components/                 # React UI components & chart views
│   └── package.json                # Frontend package manifest
├── docs/                           # Comprehensive Project Documentation
│   ├── setup.md                    # Installation & environment setup guide
│   ├── architecture.md             # System architecture & agent workflow
│   ├── api_reference.md            # REST API & MCP tool specifications
│   ├── dataset_management.md       # Multi-source datasets & schema mapping
│   └── evaluation_and_benchmarking.md # Evaluation metrics & benchmarking
├── pixi.toml                       # Pixi environment & task configuration
├── pyproject.toml                  # Python linters & type checkers config
├── .env.example                    # Environment variable template
└── README.md                       # Main project README

---

📖 Complete Documentation Index

For in-depth guides and detailed technical specifications, refer to the documents in the docs/ directory:

• 🛠️ Setup & Installation Guide: Environment requirements, configuration, and build instructions.
• 🏗️ System Architecture & Agent Workflow: Deep dive into the LangGraph state machine, Gemini planner, and MCP tools.
• 🔌 API & MCP Reference: Detailed REST API endpoints and MCP tool schema definitions.
• 📊 Dataset Management & Schema Engine: Multi-source data importing, HuggingFace/Kaggle integration, and auto-mapping.
• 🎯 Evaluation & Benchmarking: Benchmarking methodology, evaluation metrics, and performance audit tools.

---

🧪 Testing & Quality Assurance

Run code quality checks and tests via Pixi tasks:

# Run unit tests
pixi run test

# Run code linter
pixi run lint

# Check type annotations
pixi run typecheck

# Run full benchmark suite
pixi run benchmark

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.