README.md

---
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:
   
```bash
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\\Scripts\\activate     # Windows
```

3. Install dependencies:
   
```bash
pip install -r requirements.txt
```

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

## Usage

### Quick Start

```python
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

```bash
python main.py
```

Access the UI at `http://localhost:7860`

### Docker

```bash
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
```