# ClarityGate: Enterprise Document & KYC Image Quality Assessment & Blur Shield Agent

> **Ultra-Lightweight, CPU-Optimized Pre-filtering Gatekeeper for Document Onboarding & iDAX Intelligent OCR**  
> *Developed for LOLC Technologies AI Engineering*

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-green.svg)](https://fastapi.tiangolo.com/)
[![ONNX Runtime](https://img.shields.io/badge/ONNX_Runtime-CPU_Optimized-orange.svg)](https://onnxruntime.ai/)
[![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-purple.svg)](https://modelcontextprotocol.io/)
[![Benchmark Accuracy](https://img.shields.io/badge/Benchmark_Accuracy-94.3%25-brightgreen.svg)](#benchmark-results)

---

## 📌 Problem Overview

During digital customer onboarding, e-KYC, and cheque clearing, users upload images of critical personal and financial documents:
- **Sri Lankan National Identity Cards (NIC)**: Old laminated paper cards and New Smart Polycarbonate cards.
- **Sri Lankan Bank Cheques**: LOLC, Commercial Bank, BOC, HNB, Sampath cheques with MICR clearing bands.
- **Passports**: Laminated photo pages with 2-line bottom Machine Readable Zones (MRZ).
- **KYC Live Selfies**: Mobile front-camera customer portraits for 1:1 facial biometric matching.
- **Signed KYC Forms & Contracts**: Agreements requiring handwritten signatures.

When images are degraded by **motion blur, lens defocus, flash glare, heavy shadows, or edge cropping**, downstream Intelligent OCR engines (**`iDAX`**) fail, extracting corrupted data and wasting expensive compute resources.

**ClarityGate** solves this by serving as an **upstream intelligent gatekeeper**:
1. Pre-filters every image in **~350 ms on CPU** with **zero GPU requirements** and minimal memory footprint (~58 MB RAM).
2. **If Clear**: Passes the image and quality metadata cleanly to **`iDAX`** for OCR extraction.
3. **If Defective**: Intercepts the request and immediately delivers **empathetic, prescriptive, multilingual instructions** (English, Sinhala, Tamil) explaining *exactly* how the user can capture a winning photo (e.g., *"Turn off camera flash"*, *"Hold phone steady"*, *"Ensure all 4 card corners are visible"*).

---

## 🏆 Benchmark Results

Evaluated on 35 standardized Sri Lankan document samples across Old NIC, Smart NIC, Cheques, Passports, and Selfies under controlled real-world degradations:

| Model Candidate | Accuracy (%) | Precision (%) | Recall (%) | F1-Score (%) | Mean Latency (ms) | Memory (RAM) | GPU Req |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| **Laplacian Variance (OpenCV)** | 48.57% | 21.74% | 100.0% | 35.71% | 5.97 ms | ~8.0 MB | No (CPU) |
| **Tenengrad Gradient Energy** | 14.29% | 14.29% | 100.0% | 25.00% | 5.16 ms | ~8.5 MB | No (CPU) |
| **2D FFT Spectral Ratio** | 85.71% | 0.00% | 0.00% | 0.00% | 4.14 ms | ~12.0 MB | No (CPU) |
| **DocForensics ONNX (Hugging Face)** | 37.14% | 18.52% | 100.0% | 31.25% | 224.22 ms | ~42.0 MB | No (CPU) |
| **ClarityGate Hybrid Ensemble (Novel)** | **94.29%** | **71.43%** | **100.0%** | **83.33%** | **355.86 ms** | **~58.0 MB** | **No (CPU)** |

### Error Rates
- **False Positive Rate (FPR)**: Only **6.67%** (catches 28 out of 30 defective images).
- **False Negative Rate (FNR)**: **0.00%** (100% of clear images successfully pass without false rejections).

---

## 🏗️ Architecture & Component Stack

```
Image-blur-unclear-detector/
├── configs/
│   ├── default_config.yaml           # Thresholds, timeouts, iDAX endpoint config
│   └── document_profiles.json        # Policies for Sri Lankan NIC, Cheque, Passport, Selfie
├── core/
│   ├── cv_metrics.py                 # LapM, Tenengrad, 2D FFT, Motion blur anisotropy, Glare heatmap, Framing
│   ├── face_assessor.py              # UltraFace ONNX (1.2MB, ~10ms) + Haar fallback for portrait ROIs
│   ├── signature_assessor.py         # Ink continuity & stroke sharpness assessor for cheques/forms
│   ├── docforensics_engine.py        # Hugging Face DocForensics ONNX (8.8MB) layout & condition signals
│   ├── customer_feedback.py          # Multilingual prescriptive guidance (English, Sinhala, Tamil)
│   ├── idax_connector.py             # Circuit breaker proxy & forwarding to iDAX Intelligent OCR
│   └── quality_engine.py             # Master Multi-Stage Hybrid Ensemble Orchestrator
├── models/
│   ├── docforensics/                 # Local Hugging Face docforensics-layout-s.onnx weights
│   └── face/                         # Local UltraFace version-RFB-320.onnx weights
├── agent/
│   ├── clarity_agent.py              # Autonomous Agentic wrapper with decision reasoning traces
│   ├── client_sdk.py                 # Enterprise Python SDK (Embedded in-process & Remote REST)
│   └── mcp_server.py                 # Model Context Protocol (MCP) server for AI Agents
├── api/
│   ├── app.py                       # FastAPI application instance with CORS & Swagger docs
│   ├── routes.py                     # /assess, /assess-base64, /idax/gatekeeper, /health, /profiles
│   └── schemas.py                    # Pydantic v2 validation models
├── dataset/
│   ├── generate_sri_lankan_dataset.py # Synthetic Sri Lankan Old/Smart NIC, Cheque, Passport generator
│   ├── augmentations.py              # Defect simulation (defocus blur, motion smear, glare, shadows)
│   └── test_samples/                 # High-resolution benchmark sample catalog
├── evaluation/
│   ├── benchmark_models.py           # Multi-model comparative benchmark suite
│   └── metrics_reporter.py           # Markdown table formatter
├── tests/
│   └── test_comprehensive.py         # 10/10 passing unit & integration tests
├── run_server.py                     # REST API Server entry point
├── run_mcp.py                        # MCP Server entry point
├── requirements.txt
├── ARCHITECTURE.md                   # Comprehensive technical architecture blueprint
└── README.md
```

---

## 🚀 Quickstart & Installation

### 1. Install Dependencies
```bash
pip install -r requirements.txt
```

### 2. Run Comprehensive Test Suite
```bash
python -m pytest tests/test_comprehensive.py -v
```
*(All 10 tests will run and pass in ~4 seconds).*

### 3. Generate Benchmark Dataset
```bash
python -m dataset.generate_sri_lankan_dataset
```

### 4. Run Model Benchmark
```bash
python -m evaluation.benchmark_models
```

---

## 🌐 Running the REST API Server

Launch the high-performance FastAPI server:
```bash
python run_server.py
```
- **Interactive Swagger Documentation**: `http://localhost:8000/docs`
- **ReDoc Documentation**: `http://localhost:8000/redoc`
- **Health Check**: `http://localhost:8000/api/v1/health`

### Key Endpoints:
1. `POST /api/v1/quality/assess`: Standard multipart image upload.
2. `POST /api/v1/quality/assess-base64`: Base64 encoded JSON for mobile apps.
3. `POST /api/v1/idax/gatekeeper`: Gatekeeper circuit breaker proxy. Forwards to iDAX if clear; intercepts with customer advice if defective.
4. `GET /api/v1/profiles`: Configured thresholds and document rules.
5. `GET /api/v1/benchmark-report`: Latest comparative benchmark metrics.

---

## 🤖 Running the MCP Server (Model Context Protocol)

Integrate ClarityGate as a native tool provider for AI Agents (Claude Desktop, Antigravity Agent, Gemini CLI):
```bash
python run_mcp.py
```

### Exposed MCP Tools:
- `assess_document_clarity`: Full quality score and defect diagnostics.
- `validate_and_route_to_idax`: Gatekeeper circuit breaker forwarding to iDAX OCR.
- `get_document_profiles`: Document-specific threshold rules.
- `get_benchmark_metrics`: Comparative evaluation metrics.

---

## 💻 Python Client SDK Usage

### Option A: Embedded In-Process Mode (Fastest, Zero Network Overhead)
```python
from agent.client_sdk import ClarityGatekeeperClient

# In-process engine
client = ClarityGatekeeperClient(embedded=True)

# Assess Sri Lankan Smart NIC
result = client.assess_file("my_smart_nic.jpg", doc_type="sri_lankan_smart_nic", language="si")

if result.is_clear:
    print(f"Document Approved! Score: {result.overall_clarity_score}/100")
else:
    print(f"Customer Advice: {result.customer_feedback.message}")
    print(f"Action: {result.customer_feedback.action_required}")
```

### Option B: Remote REST API Mode
```python
from agent.client_sdk import ClarityGatekeeperClient

client = ClarityGatekeeperClient(base_url="http://localhost:8000")

# Check cheque and route to iDAX
response = client.verify_and_route_to_idax("cheque.jpg", doc_type="sri_lankan_cheque")
print(response)
```

---

## 🛡️ Multilingual Customer Feedback

| Condition | Action Required | English Feedback | Sinhala Feedback (සිංහල) | Tamil Feedback (தமிழ்) |
| :--- | :--- | :--- | :--- | :--- |
| **Flash Glare** | `TURN_OFF_FLASH` | Camera flash or glare is reflecting off the document. Please turn off your flash and avoid direct reflections. | කැමරා ෆ්ලෑෂ් (Flash) එළිය ලේඛනය මත පරාවර්තනය වේ. කරුණාකර Flash ක්‍රියා විරහිත කර නැවත ගන්න. | கேமரா ஃபிளாஷ் வெளிச்சம் ஆவணத்தில் பிரதிபலிக்கிறது. தயவுசெய்து Flash ஐ அணைத்துவிட்டு எடுக்கவும். |
| **Motion Blur** | `HOLD_STEADY` | The photo is blurry due to camera movement. Please hold your phone steady with both hands and tap to focus. | කැමරාව සෙලවීම නිසා ඡායාරූපය බොඳ වී ඇත. කරුණාකර දෑතින්ම දුරකථනය ස්ථාවරව තබාගෙන නැවත ඡායාරූපයක් ගන්න. | கேமரா அசைவு காரணமாக படம் மங்கலாக உள்ளது. தயவுசெய்து தொலைபேசியை அசையாமல் பிடித்து மீண்டும் எடுக்கவும். |
| **Defocus Blur**| `TAP_TO_FOCUS` | The document is out of focus. Please tap the screen to focus or move the camera slightly back. | ලේඛනයේ අකුරු පැහැදිලි නැත. කරුණාකර තිරය ස්පර්ශ කර (Tap to focus) නැවත ගන්න. | ஆவணம் தெளிவாக இல்லை. திரையைத் தொட்டு ஃபோகஸ் செய்து மீண்டும் புகைப்படம் எடுக்கவும். |
| **Shadows/Dark** | `IMPROVE_LIGHTING` | The photo is too dark or shadowed. Please move to a well-lit area or switch on indoor lights. | ඡායාරූපය අඳුරු වැඩියි. කරුණාකර හොඳින් ආලෝකය ඇති ස්ථානයකදී ඡායාරූපය ලබාගන්න. | படம் மிகவும் இருட்டாக உள்ளது. வெளிச்சம் உள்ள இடத்திற்குச் சென்று படம் எடுக்கவும். |
| **Cutoff Edges** | `REFRAME_FULL_DOCUMENT` | The document corners or edges are cut off. Please ensure all 4 borders of the card are visible in the frame. | ලේඛනයේ දාර හෝ කොන් කැපී ඇත. කරුණාකර සම්පූර්ණ ලේඛනයේ කොන් 4ම පෙනෙන සේ ඡායාරූපය ගන්න. | ஆவணத்தின் ஓரங்கள் வெட்டப்பட்டுள்ளன. ஆவணத்தின் 4 முனைகளும் தெரியும் வண்ணம் படம் எடுக்கவும். |

---

## 📜 License & Compliance

Proprietary enterprise solution engineered for LOLC Technologies banking and financial software platforms. Meets Central Bank of Sri Lanka (CBSL) e-KYC compliance standards.