syedkhizarrayaz/BM-AI-Analysis-And-Alert-Prioritization-Agent

SystemZ-AI: AML Alert Classification and Analysis System

Table of Contents

• —Overview
• —Architecture
• —Features
• —Prerequisites
• —Local Development Setup
• —Docker Setup
• —Building Docker Image
• —Environment Variables
• —API Documentation
• —Code Structure
• —LLM Integration
• —Database Configuration
• —Troubleshooting

Overview

SystemZ-AI is an Anti-Money Laundering (AML) alert classification and analysis system that combines machine learning models with Large Language Models (LLMs) to automatically classify and analyze suspicious transaction alerts. The system provides multiple analysis methods ranging from ultra-fast template-based responses to comprehensive LLM-powered analysis reports.

Key Capabilities

• —ML-Based Alert Classification: Uses a trained Random Forest model to predict whether alerts should be escalated or closed
• —Multi-Method Analysis: Supports OpenAI GPT models, local Ollama LLMs, and hybrid template+LLM approaches
• —Ultra-Fast Analysis: Template-based system for millisecond response times
• —Comprehensive Reports: Generates detailed AML investigation reports with structured sections
• —Streaming Support: Real-time streaming responses for analysis generation
• —Email Alerts: Automated email notifications for high-risk alerts

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     FastAPI Application                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Auth API   │  │  Model API   │  │ Analysis API │     │
│  │  (app.py)    │  │ (runmodel.py)│  │(analysisreport│     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
         │                    │                    │
         │                    │                    │
    ┌────▼────┐          ┌────▼────┐         ┌────▼────┐
    │  JWT    │          │   ML     │         │   LLM   │
    │  Auth   │          │  Model   │         │ Systems │
    └─────────┘          └──────────┘         └─────────┘
                              │                    │
                              │                    │
                         ┌────▼────┐         ┌────▼────┐
                         │Database │         │ Ollama  │
                         │(SQL)   │         │ /OpenAI │
                         └─────────┘         └─────────┘

Components

1. 1.Authentication Module (auth.py): JWT-based authentication with bcrypt password hashing
2. 2.Model Processing (runmodel.py): ML model inference and data preprocessing
3. 3.Analysis Generation (analysisreport.py): Multiple analysis methods (OpenAI, Local LLM, Hybrid)
4. 4.Email Service (sendemail.py): Automated email alerts for compliance teams
5. 5.LLM Integration:
6. 6.localLLM.py: Ollama local LLM wrapper
7. 7.hybrid_template_llm_aml.py: Hybrid template+LLM system
8. 8.hybrid_ultra_fast_aml.py: Ultra-fast template-based system

Features

Analysis Methods

1. 1.OpenAI GPT Analysis (generateanalysisjson):
2. 2.Uses OpenAI GPT models via direct API calls
3. 3.Comprehensive analysis with structured output
4. 4.Supports streaming responses

1. 1.Local LLM Analysis (get_analysis_json_local_llm):
2. 2.Uses Ollama local LLM models (qwen2.5:1.5b, granite3.1-moe:3b, etc.)
3. 3.Optimized for performance with caching
4. 4.No external API dependencies

1. 1.Hybrid Template+LLM (generateanalysis):
2. 2.Templates for data formatting
3. 3.LLM for intelligent analysis
4. 4.Supports both local and cloud LLMs
5. 5.Configurable via Cloud, llm_on_server, and url parameters

1. 1.Ultra-Fast Template System (get_analysis_json_ultra_fast):
2. 2.Millisecond response times
3. 3.Rule-based risk assessment
4. 4.Pre-computed templates for common scenarios

ML Model Features

• —Preprocessing Pipeline: Handles missing data, feature engineering, and encoding
• —Risk Adjustment: Adjusts predictions based on KYC risk levels
• —STR Count Calculation: Tracks Suspicious Transaction Report history
• —Transaction Filtering: Extracts and formats transaction data from XML/JSON

Prerequisites

For Local Development

• —Python 3.12.5 or higher
• —pip (Python package manager)
• —Ollama (for local LLM support) - Installation Guide
• —SQL Server (optional, for database features)
• —Git

For Docker

• —Docker Engine 20.10+
• —Docker Compose 2.0+

System Requirements

• —CPU: 4+ cores recommended
• —RAM: 8GB minimum, 16GB recommended
• —Storage: 10GB free space
• —GPU: Optional but recommended for LLM inference

Local Development Setup

Step 1: Clone the Repository

git clone <repository-url>
cd SystemZ-AI

Step 2: Create Virtual Environment

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

Step 4: Install and Setup Ollama

Windows

1. 1.Download Ollama from https://ollama.com/download
2. 2.Install and start Ollama service
3. 3.Pull required model:

ollama pull granite3.1-moe:3b
# or
ollama pull qwen2.5:1.5b

Linux/Mac

curl -fsSL https://ollama.com/install.sh | sh
ollama pull granite3.1-moe:3b

Step 5: Create Environment File

Create a .env file in the project root:

# OpenAI Configuration (for cloud LLM)
OPENAI_API_KEY=your_openai_api_key_here
ASSISTANT_ID=your_openai_assistant_id_here

# Database Configuration (optional)
DB_CONNECTION_STR=mssql+pyodbc://username:password@server/database?driver=ODBC+Driver+17+for+SQL+Server
DATA_TABLE=YourDataTable
ACCUMULATED_DATA=YourAccumulatedDataTable
ANALYSIS_TABLE=YourAnalysisTable
PREDICTION_FLAG=1

# Model File
MODEL_FILE=AMLClassificationModel2.pkl

# Authentication
SECRET_KEY=your_secret_key_here_min_32_chars
USERNAME=admin
PASSWORD=your_password_here

# Email Configuration (optional)
EMAIL_PASSWORD=your_email_app_password
FROM_EMAIL=your_email@example.com

# Ollama Configuration (optional, defaults shown)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=granite3.1-moe:3b

# OpenRouter Configuration (for cloud LLM alternative)
OPENROUTER_API_KEY=your_openrouter_key_here
OPENROUTER_MODEL=xiaomi/mimo-v2-flash:free
OPENROUTER_SITE_URL=https://your-site.com
OPENROUTER_SITE_NAME=SystemZ-AI

Step 6: Verify Model File

Ensure AMLClassificationModel2.pkl exists in the project root. This is the trained ML model for alert classification.

Step 7: Run the Application

# Start Ollama (if not running as service)
ollama serve

# In another terminal, start the FastAPI app
uvicorn app:app --host 0.0.0.0 --port 8000 --reload

The API will be available at:

• —API: http://localhost:8000
• —Interactive Docs: http://localhost:8000/docs
• —Alternative Docs: http://localhost:8000/redoc

Step 8: Test the Setup

# Test authentication
curl -X POST "http://localhost:8000/api/ai-service/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=your_password"

# Test health (if endpoint exists)
curl http://localhost:8000/docs

Docker Setup

Quick Start with Docker Compose

1. 1.Create `.env` file (see Local Development Setup Step 5)

1. 1.Build and run with Docker Compose:

docker-compose up --build

This will:

• —Build the Docker image
• —Start Ollama service inside the container
• —Pull the required LLM model
• —Start the FastAPI application

1. 1.Access the API:
2. 2.API: http://localhost:8000
3. 3.Docs: http://localhost:8000/docs

Docker Compose Configuration

The docker-compose.yml file includes:

• —Ports: 8000 (FastAPI), 11434 (Ollama)
• —Health Check: Automatic health monitoring
• —Environment Variables: Loaded from .env file
• —Restart Policy: unless-stopped

Customize Docker Compose

Edit docker-compose.yml to:

• —Change ports mapping
• —Add volume mounts for persistent data
• —Configure resource limits
• —Add additional services

Building Docker Image

Build Options

Standard Build

docker build -t systemz-ai:latest .

Build with Custom Ollama Configuration

docker build \
  --build-arg OLLAMA_BASE_URL=http://localhost:11434 \
  --build-arg OLLAMA_MODEL=granite3.1-moe:3b \
  -t systemz-ai:latest .

Build with Different Python Version

Edit Dockerfile line 2:

FROM python:3.12.5-slim

Build Process Details

The Dockerfile performs these steps:

1. 1.Base Image: Python 3.12.5 slim
2. 2.System Dependencies:
3. 3.curl, wget, git
4. 4.build-essential
5. 5.Ollama installation
6. 6.Python Dependencies: Installs from requirements.txt
7. 7.Application Files: Copies all project files
8. 8.Ports: Exposes 8000 (FastAPI) and 11434 (Ollama)
9. 9.Startup: Runs start.sh which:
10. 10.Starts Ollama service
11. 11.Waits for Ollama to be ready
12. 12.Pulls the model if needed
13. 13.Starts FastAPI with uvicorn

Running the Built Image

# Run with environment variables
docker run -d \
  --name systemz-ai \
  -p 8000:8000 \
  -p 11434:11434 \
  --env-file .env \
  systemz-ai:latest

# Or with inline environment variables
docker run -d \
  --name systemz-ai \
  -p 8000:8000 \
  -p 11434:11434 \
  -e OPENAI_API_KEY=your_key \
  -e SECRET_KEY=your_secret \
  -e USERNAME=admin \
  -e PASSWORD=your_password \
  systemz-ai:latest

Docker Image Optimization

For production, consider:

• —Multi-stage builds to reduce image size
• —Using Alpine Linux base image
• —Removing build dependencies after installation
• —Using specific version tags instead of latest

Environment Variables

Required Variables

Optional Variables

OpenAI Configuration

• —OPENAI_API_KEY: OpenAI API key for GPT models
• —ASSISTANT_ID: OpenAI Assistant ID (if using assistants)

Database Configuration

• —DB_CONNECTION_STR: SQL Server connection string
• —DATA_TABLE: Table name for alert data
• —ACCUMULATED_DATA: Table name for accumulated data
• —ANALYSIS_TABLE: Table name for analysis results
• —PREDICTION_FLAG: Flag value for predictions (default: 1)

Model Configuration

• —MODEL_FILE: Path to ML model file (default: AMLClassificationModel2.pkl)

Email Configuration

• —EMAIL_PASSWORD: Email account app password
• —FROM_EMAIL: Sender email address

Ollama Configuration

• —OLLAMA_BASE_URL: Ollama API URL (default: http://localhost:11434)
• —OLLAMA_MODEL: Model name (default: granite3.1-moe:3b)

OpenRouter Configuration (Cloud LLM Alternative)

• —OPENROUTER_API_KEY: OpenRouter API key
• —OPENROUTER_MODEL: Model name (default: xiaomi/mimo-v2-flash:free)
• —OPENROUTER_SITE_URL: Your site URL
• —OPENROUTER_SITE_NAME: Your site name

API Documentation

Authentication

Note: Authentication is optional and only required when integrating with external systems. For internal system use, authentication is disabled by default.

If you need authentication for external integrations:

Endpoint: POST /api/ai-service/token

Request:

Content-Type: application/x-www-form-urlencoded

username=admin&password=your_password

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Usage: Include token in Authorization header:

Authorization: Bearer <access_token>

Main API Endpoints

See API_DOCUMENTATION.md for complete Swagger/OpenAPI documentation.

Quick Reference

1. 1.Token Generation (Optional): POST /api/ai-service/token
2. 2.Predict Alert Priority: POST /api/ai-service/predictalertpriority
3. 3.Generate AML Analysis (OpenAI): POST /api/ai-service/generateamlanalysisoai
4. 4.Generate AML Analysis (Hybrid): POST /api/ai-service/generateamlanalysis
5. 5.Generate AML Analysis (Streaming): POST /api/ai-service/generateamlanalysisstreaming
6. 6.Send Email Alerts (JSON) (Optional/Future): POST /api/ai-service/sendalertsemailjson
7. 7.Send Email Alerts (DataFrame) (Optional/Future): POST /api/ai-service/sendalertsemaildataframe

Code Structure

SystemZ-AI/
├── app.py                      # FastAPI main application
├── auth.py                     # JWT authentication module
├── config.py                   # Environment configuration
├── runmodel.py                 # ML model processing and prediction
├── analysisreport.py           # Analysis generation (multiple methods)
├── sendemail.py                # Email alert service
├── localLLM.py                 # Ollama local LLM wrapper
├── llmeventhandler.py          # OpenAI streaming event handler
├── hybrid_template_llm_aml.py # Hybrid template+LLM system
├── hybrid_ultra_fast_aml.py   # Ultra-fast template system
├── requirements.txt            # Python dependencies
├── Dockerfile                  # Docker image definition
├── docker-compose.yml          # Docker Compose configuration
├── start.sh                    # Container startup script
├── AMLClassificationModel2.pkl # Trained ML model
├── .env                        # Environment variables (create this)
└── README.md                   # This file

Key Modules Explained

app.py

• —FastAPI application entry point
• —OAuth2 token endpoint
• —Router registration
• —Logging configuration

auth.py

• —JWT token creation and validation
• —Password hashing with bcrypt
• —User authentication
• —Token expiration (30,000,000 minutes by default)

runmodel.py

• —ML model loading and inference
• —Data preprocessing pipeline
• —Feature engineering
• —Prediction generation
• —Database integration

analysisreport.py

• —Multiple analysis methods:
• —OpenAI GPT direct calls
• —Local LLM (Ollama)
• —Hybrid template+LLM
• —Ultra-fast templates
• —Streaming support
• —KYC profile generation
• —Transaction data processing

hybrid_template_llm_aml.py

• —Hybrid analysis system
• —Template-based data formatting
• —LLM-powered analysis
• —Cloud and local LLM support
• —Comprehensive AML report generation

localLLM.py

• —Ollama API wrapper
• —Model preloading
• —Response caching
• —Connection pooling
• —Performance optimization

LLM Integration

Supported Models

Local Models (Ollama)

• —granite3.1-moe:3b (recommended)
• —granite4:350m (fastest)
• —qwen2.5:1.5b
• —tinyllama:latest
• —llama3.2:1b
• —deepseek-r1:1.5b

Cloud Models

• —OpenAI GPT models (via OPENAI_API_KEY)
• —OpenRouter models (via OPENROUTER_API_KEY)

Model Selection

For Speed: Use granite4:350m or tinyllama:latest For Quality: Use granite3.1-moe:3b or cloud models For Balance: Use qwen2.5:1.5b

Switching Models

Local Development:

# Set in .env
OLLAMA_MODEL=granite3.1-moe:3b

# Or pull new model
ollama pull granite3.1-moe:3b

Docker:

# Set in docker-compose.yml or .env
OLLAMA_MODEL=granite3.1-moe:3b

Database Configuration

SQL Server Setup

1. 1.Connection String Format:

mssql+pyodbc://username:password@server:port/database?driver=ODBC+Driver+17+for+SQL+Server

1. 1.Required Tables:
2. 2.DATA_TABLE: Stores processed alert data
3. 3.ACCUMULATED_DATA: Source data for predictions
4. 4.ANALYSIS_TABLE: Stores analysis results

1. 1.Table Schema (example):

-- Accumulated Data Table
CREATE TABLE AccumulatedData (
    AlertID INT PRIMARY KEY,
    FocusColumnValue NVARCHAR(255),
    ScenarioName NVARCHAR(255),
    CreateDate DATETIME,
    AlertScore FLOAT,
    -- ... other fields
);

-- Data Table (for predictions)
CREATE TABLE DataTable (
    AlertID INT,
    Prediction INT,
    -- ... other fields
);

-- Analysis Table
CREATE TABLE AnalysisTable (
    AlertID INT,
    FocusColumnValue NVARCHAR(255),
    html_analysis NVARCHAR(MAX)
);

Running Without Database

The system can run without a database. Set DB_CONNECTION_STR to empty or omit it. Analysis endpoints will work with JSON input only.

Troubleshooting

Common Issues

1. Ollama Not Starting

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama manually
ollama serve

# Check logs
ollama logs

2. Model Not Found

# List available models
ollama list

# Pull the model
ollama pull granite3.1-moe:3b

3. Port Already in Use

# Find process using port 8000
# Windows
netstat -ano | findstr :8000

# Linux/Mac
lsof -i :8000

# Kill process or change port in uvicorn command
uvicorn app:app --host 0.0.0.0 --port 8001

4. Database Connection Failed

• —Verify connection string format
• —Check SQL Server is running
• —Verify credentials
• —Ensure ODBC driver is installed (for local development)

5. Import Errors

# Reinstall dependencies
pip install --force-reinstall -r requirements.txt

# Check Python version
python --version  # Should be 3.12.5+

6. Docker Build Fails

# Clear Docker cache
docker builder prune

# Rebuild without cache
docker build --no-cache -t systemz-ai:latest .

7. Authentication Fails

• —Verify SECRET_KEY is set (min 32 characters)
• —Check USERNAME and PASSWORD in .env
• —Ensure password is hashed correctly in auth.py

Log Files

The application creates log files:

• —authapi.log: Authentication logs
• —runmodelapi.log: Model processing logs
• —analysisapi.log: Analysis generation logs
• —emailapi.log: Email service logs

Performance Optimization

1. 1.Use GPU for LLM:
2. 2.Install CUDA drivers
3. 3.Ollama will auto-detect GPU

1. 1.Increase Threads:
2. 2.Edit localLLM.py num_thread parameter
3. 3.Adjust based on CPU cores

1. 1.Enable Caching:
2. 2.Already enabled in localLLM.py
3. 3.Cache size limited to 1000 entries

1. 1.Use Faster Models:
2. 2.granite4:350m for speed
3. 3.granite3.1-moe:3b for quality

License

Benchmatrix License