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

📌 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").

Related MCP server: MCP Mortgage Server

🏆 Benchmark Results

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

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

pip install -r requirements.txt

2. Run Comprehensive Test Suite

python -m pytest tests/test_comprehensive.py -v

(All 10 tests will run and pass in ~4 seconds).

3. Generate Benchmark Dataset

python -m dataset.generate_sri_lankan_dataset

4. Run Model Benchmark

python -m evaluation.benchmark_models

🌐 Running the REST API Server

Launch the high-performance FastAPI server:

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):

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)

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

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

📜 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.