README.md

metadata

title: AI Financial Reconciliation Engine
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

🧠 AI Financial Reconciliation Engine

Automated Financial Auditing using Machine Learning and LLMs.

🚀 Overview

The AI Financial Reconciliation Engine is an intelligent system designed to automate the process of matching internal accounting records (Books) with external tax filings (GST). By combining Fuzzy Logic, AI Semantic Embeddings, and LLM reasoning, the system identifies discrepancies, detects fraudulent anomalies, and provides natural language explanations for auditors.

✨ Features

• Intelligent Matching: Combines basic matching with Fuzzy and AI semantic analysis to reconcile records even with typos or name variations.
• Anomaly Detection: Uses the IsolationForest algorithm to detect unusual transaction patterns and high-risk invoices.
• AI Explanations: Integrates Mistral LLM to provide human-readable audit comments for every discrepancy.
• Interactive Dashboard: A professional Gradio interface with summary metrics, risk-sorted results, and CSV export.
• Graph Fraud Network: Visualizes circular trading and multi-hop tax siphoning fraud rings using NetworkX and Matplotlib.
• Persistent Vector Memory: Uses C++ compiled FAISS algorithms to permanently remember vendor vector embeddings.
• Deployment Ready: Containerized with Docker and hosted on HuggingFace Spaces.

🛠 Tech Stack

• Languages: Python
• AI/ML: Scikit-Learn, Sentence-Transformers, RapidFuzz
• Fraud Engine: FAISS, NetworkX, Matplotlib
• LLM: Mistral AI API
• Frontend: Gradio
• Infrastructure: Docker, HuggingFace Spaces

📂 Installation (Local)

1. Clone the repository.
2. Install dependencies: pip install -r requirements.txt
3. Set your MISTRAL_API_KEY in a .env file.
4. Run the app: python main.py

Prerequisites

• Python 3.11+
• Virtual Environment (venv)

Setup

1. Clone the repository
2. Create and activate virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\\Scripts\\activate     # Windows

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment variables:
   • Copy .env.example to .env
   • Add your API keys

Usage

Quick Start

from utils import create_sample_data
from reconciliation import ReconciliationEngine
from anomaly import AnomalyDetector

# Create sample data
data = create_sample_data(num_records=100)
source_df = data['source']
target_df = data['target']

# Run reconciliation
engine = ReconciliationEngine(threshold=85.0)
result = engine.reconcile(source_df, target_df, 'VendorName', 'VendorName', 'Amount')

# Detect anomalies
detector = AnomalyDetector(contamination=0.05)
anomaly_result = detector.detect_anomalies(source_df)

Web Interface

python main.py

Access the UI at http://localhost:7860

Docker

docker build -t reconciliation-engine .
docker run -p 7860:7860 reconciliation-engine

Project Structure

├── sample_data/         # Live CSV data and scenarios
├── main.py                 # Main FastAPI backend serving UI
├── reconciliation.py      # Core reconciliation engine & FAISS Index
├── anomaly.py             # Anomaly detection module
├── fraud_graph.py         # NetworkX Circular Trading Detector
├── gst_api.py             # Real-time Local Registry Gateway
├── generate_real_data.py  # Script to generate 1800+ realistic rows
├── llm_explainer.py       # LLM-powered explanations
├── utils.py               # Utility functions
├── requirements.txt    # Python dependencies
├── Dockerfile         # Docker configuration
├── .env               # Environment variables
└── README.md          # This file