Update app.py

app.py

@@ -1,5 +1,4 @@
 from fastapi import FastAPI, UploadFile, File
-from PIL import Image
 import easyocr
 import cv2
 import numpy as np
@@ -8,6 +7,10 @@ import os
 
 app = FastAPI()
 
+# =========================
+# LOAD OCR MODEL
+# =========================
+
 reader = easyocr.Reader(['en'])
 
 # =========================
@@ -15,179 +18,401 @@ reader = easyocr.Reader(['en'])
 # =========================
 
 def is_blurry(image):
+
     gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
-    variance = cv2.Laplacian(gray, cv2.CV_64F).var()
 
-    if variance < 100:
-        return True
+    variance = cv2.Laplacian(
+        gray,
+        cv2.CV_64F
+    ).var()
 
-    return False
+    return variance < 100
 
 
-def is_too_dark(image):
-    brightness = np.mean(image)
+def is_dark(image):
 
-    if brightness < 50:
-        return True
+    brightness = np.mean(image)
 
-    return False
+    return brightness < 50
 
 
 # =========================
-# OCR EXTRACTION
+# OCR TEXT EXTRACTION
 # =========================
 
 def extract_text(image_path):
 
     results = reader.readtext(image_path)
 
-    text = " ".join([r[1] for r in results]).lower()
+    text = " ".join(
+        [r[1] for r in results]
+    ).lower()
 
     return text
 
 
 # =========================
-# DOCUMENT VALIDATION
+# DOCUMENT DETECTION
 # =========================
 
 def detect_document(text):
 
+    # =========================
     # NIN
-    if (
-        "national identification number" in text
-        or "nin" in text
-    ):
-        return "nin"
-
-    # Passport
-    elif (
-        "passport" in text
-        or "federal republic of nigeria" in text
-    ):
-        return "passport"
-
-    # Driver License
-    elif (
-        "driver" in text
-        and "license" in text
-    ):
-        return "drivers_license"
-
-    # Voter Card
-    elif (
-        "voter" in text
-        or "inec" in text
-    ):
-        return "voters_card"
-
-    # Utility Bill
-    elif (
-        "electricity" in text
-        or "water bill" in text
-        or "eko electric" in text
-        or "ikeja electric" in text
-    ):
-        return "utility_bill"
-
-    # Bank Statement
-    elif (
-        "account statement" in text
-        or "transaction" in text
-        or "balance" in text
-    ):
-        return "bank_statement"
-
-    # Tenancy Agreement
-    elif (
-        "tenancy agreement" in text
-        or "landlord" in text
-        or "tenant" in text
-    ):
-        return "tenancy_agreement"
-
-    # Vehicle Plate Number
-    elif re.search(r"[A-Z]{3}-?\d{3}[A-Z]{2}", text.upper()):
-        return "vehicle_plate"
+    # =========================
+
+    nin_keywords = [
+        "national identification number",
+        "nin"
+    ]
+
+    matched_keywords = []
+
+    for keyword in nin_keywords:
+        if keyword in text:
+            matched_keywords.append(keyword)
+
+    if len(matched_keywords) > 0:
+        return {
+            "document_type": "nin",
+            "confidence": 95,
+            "matched_keywords": matched_keywords
+        }
+
+    # =========================
+    # PASSPORT
+    # =========================
+
+    passport_keywords = [
+        "passport",
+        "federal republic of nigeria"
+    ]
+
+    matched_keywords = []
+
+    for keyword in passport_keywords:
+        if keyword in text:
+            matched_keywords.append(keyword)
+
+    if len(matched_keywords) > 0:
+        return {
+            "document_type": "passport",
+            "confidence": 94,
+            "matched_keywords": matched_keywords
+        }
+
+    # =========================
+    # DRIVER LICENSE
+    # =========================
+
+    license_keywords = [
+        "driver",
+        "license"
+    ]
+
+    matched_keywords = []
+
+    for keyword in license_keywords:
+        if keyword in text:
+            matched_keywords.append(keyword)
+
+    if len(matched_keywords) >= 2:
+        return {
+            "document_type": "drivers_license",
+            "confidence": 92,
+            "matched_keywords": matched_keywords
+        }
+
+    # =========================
+    # VOTER CARD
+    # =========================
+
+    voter_keywords = [
+        "voter",
+        "inec"
+    ]
+
+    matched_keywords = []
+
+    for keyword in voter_keywords:
+        if keyword in text:
+            matched_keywords.append(keyword)
+
+    if len(matched_keywords) > 0:
+        return {
+            "document_type": "voters_card",
+            "confidence": 90,
+            "matched_keywords": matched_keywords
+        }
+
+    # =========================
+    # UTILITY BILL
+    # =========================
+
+    utility_keywords = [
+        "electricity",
+        "water bill",
+        "ikeja electric",
+        "eko electric",
+        "abuja electricity",
+        "aedc"
+    ]
+
+    matched_keywords = []
+
+    for keyword in utility_keywords:
+        if keyword in text:
+            matched_keywords.append(keyword)
+
+    if len(matched_keywords) > 0:
+        return {
+            "document_type": "utility_bill",
+            "confidence": 88,
+            "matched_keywords": matched_keywords
+        }
+
+    # =========================
+    # BANK STATEMENT
+    # =========================
+
+    bank_keywords = [
+        "account statement",
+        "transaction",
+        "balance",
+        "account number",
+        "credit",
+        "debit"
+    ]
+
+    matched_keywords = []
+
+    for keyword in bank_keywords:
+        if keyword in text:
+            matched_keywords.append(keyword)
+
+    if len(matched_keywords) > 0:
+        return {
+            "document_type": "bank_statement",
+            "confidence": 91,
+            "matched_keywords": matched_keywords
+        }
+
+    # =========================
+    # TENANCY AGREEMENT
+    # =========================
+
+    tenancy_keywords = [
+        "tenancy agreement",
+        "landlord",
+        "tenant",
+        "rent",
+        "property"
+    ]
+
+    matched_keywords = []
+
+    for keyword in tenancy_keywords:
+        if keyword in text:
+            matched_keywords.append(keyword)
+
+    if len(matched_keywords) > 0:
+        return {
+            "document_type": "tenancy_agreement",
+            "confidence": 89,
+            "matched_keywords": matched_keywords
+        }
+
+    # =========================
+    # VEHICLE PLATE NUMBER
+    # =========================
+
+    plate_match = re.search(
+        r"[A-Z]{3}-?\d{3}[A-Z]{2}",
+        text.upper()
+    )
+
+    if plate_match:
+        return {
+            "document_type": "vehicle_plate",
+            "confidence": 93,
+            "matched_keywords": [plate_match.group()]
+        }
 
     return None
 
 
 # =========================
-# MAIN API ENDPOINT
+# HOME ROUTE
 # =========================
 
-@app.post("/validate")
+@app.get("/")
+def home():
+
+    return {
+        "success": True,
+        "message": "Document Validation API Running",
+        "supported_documents": [
+            "National ID (NIN)",
+            "International Passport",
+            "Driver License",
+            "Voter Card",
+            "Vehicle with Plate Number",
+            "Utility Bill",
+            "Bank Statement",
+            "Tenancy Agreement"
+        ]
+    }
+
+
+# =========================
+# VALIDATION ENDPOINT
+# =========================
 
+@app.post("/validate")
 async def validate_document(
     file: UploadFile = File(...)
 ):
 
     try:
 
-        # SAVE IMAGE
-        temp_path = "temp.jpg"
+        # =========================
+        # SAVE FILE
+        # =========================
+
+        image_path = "temp.jpg"
 
-        with open(temp_path, "wb") as f:
+        with open(image_path, "wb") as f:
             f.write(await file.read())
 
+        # =========================
         # READ IMAGE
-        image = cv2.imread(temp_path)
+        # =========================
+
+        image = cv2.imread(image_path)
 
         if image is None:
+
             return {
                 "success": False,
-                "message": "Invalid image"
+                "message": "Invalid image",
+                "reason": "The uploaded file could not be read as an image.",
+                "suggestion": "Upload a valid JPG or PNG image."
             }
 
         # =========================
-        # IMAGE QUALITY CHECK
+        # BLUR CHECK
         # =========================
 
         if is_blurry(image):
+
             return {
                 "success": False,
-                "message": "Image is blurry"
+                "message": "Image rejected",
+                "reason": "The uploaded image is blurry.",
+                "suggestion": "Retake the photo with better focus."
             }
 
-        if is_too_dark(image):
+        # =========================
+        # DARK IMAGE CHECK
+        # =========================
+
+        if is_dark(image):
+
             return {
                 "success": False,
-                "message": "Image is too dark"
+                "message": "Image rejected",
+                "reason": "The uploaded image is too dark.",
+                "suggestion": "Take the photo in a brighter environment."
             }
 
         # =========================
-        # OCR
+        # OCR TEXT EXTRACTION
         # =========================
 
-        text = extract_text(temp_path)
+        text = extract_text(image_path)
+
+        # =========================
+        # NO TEXT FOUND
+        # =========================
 
         if len(text.strip()) == 0:
+
             return {
                 "success": False,
-                "message": "No readable text found"
+                "message": "Document rejected",
+                "reason": "No readable text was detected in the image.",
+                "suggestion": "Ensure the document is clear and fully visible."
             }
 
         # =========================
         # DOCUMENT DETECTION
         # =========================
 
-        document_type = detect_document(text)
+        document_result = detect_document(text)
+
+        # =========================
+        # UNSUPPORTED DOCUMENT
+        # =========================
+
+        if document_result is None:
 
-        if document_type is None:
             return {
                 "success": False,
-                "message": "Rejected: Unsupported document"
+                "message": "Document rejected",
+                "reason": (
+                    "The uploaded image does not match any "
+                    "supported document type."
+                ),
+                "supported_documents": [
+                    "National ID (NIN)",
+                    "International Passport",
+                    "Driver License",
+                    "Voter Card",
+                    "Vehicle with Plate Number",
+                    "Utility Bill",
+                    "Bank Statement",
+                    "Tenancy Agreement"
+                ],
+                "possible_issues": [
+                    "Image is cropped",
+                    "Text is unreadable",
+                    "Unsupported document uploaded",
+                    "Poor lighting",
+                    "Low image quality",
+                    "Document too far from camera",
+                    "Document partially hidden"
+                ],
+                "ocr_preview": text[:300]
             }
 
+        # =========================
+        # SUCCESS RESPONSE
+        # =========================
+
         return {
             "success": True,
-            "document_type": document_type,
-            "extracted_text": text[:300]
+            "message": "Document verified successfully",
+            "document_type": document_result["document_type"],
+            "confidence": document_result["confidence"],
+            "matched_keywords": (
+                document_result["matched_keywords"]
+            ),
+            "ocr_preview": text[:300]
         }
 
     except Exception as e:
 
         return {
             "success": False,
-            "message": str(e)
-        }
+            "message": "System error",
+            "reason": str(e)
+        }
+
+    finally:
+
+        # =========================
+        # CLEAN TEMP FILE
+        # =========================
+
+        if os.path.exists("temp.jpg"):
+            os.remove("temp.jpg")