initial push

README.md

@@ -1,12 +1,10 @@
 ---
-title: HDFC EMBEDDING RA MATCHING
-emoji: 📉
+title: GEN AI Record Level Matching
+emoji: 🔍
 colorFrom: purple
-colorTo: green
+colorTo: orange
 sdk: gradio
-sdk_version: 6.9.0
-app_file: app.py
+sdk_version: "4.44.0"
+app_file: frontend/app.py
 pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---

backend/config/common.properties

@@ -0,0 +1,111 @@
+[MAPPING_DICT]
+
+CITY_MAPPING = {"MUMBAI":["MUMBAI","BOMBAY","MUMBAI SUBURBAN"],"DELHI":["DELHI","NEW DELHI","DELHI NCR","NCT OF DELHI","SEELAMPUR","SHAHDARA","DWARKA","ROHINI","PITAMPURA","KAROL BAGH","LAJPAT NAGAR","SAKET","JANAKPURI","MAYUR VIHAR","VASANT KUNJ","OKHLA"],"BENGALURU":["BENGALURU","BANGALORE","BENGALURU URBAN"],"HYDERABAD":["HYDERABAD","SECUNDERABAD","HYDERABAD CITY"],"CHENNAI":["CHENNAI","MADRAS","CHENNAI CITY"],"KOLKATA":["KOLKATA","CALCUTTA","KOLKATA CITY"],"PUNE":["PUNE","POONA"],"AHMEDABAD":["AHMEDABAD","AMDAVAD"],"JAIPUR":["JAIPUR","PINK CITY"],"LUCKNOW":["LUCKNOW","LAKHNAU"],"KANPUR":["KANPUR","CAWNPORE"],"NAGPUR":["NAGPUR"],"INDORE":["INDORE"],"THANE":["THANE","THANA"],"BHOPAL":["BHOPAL"],"VISAKHAPATNAM":["VISAKHAPATNAM","VIZAG","VISHAKHAPATNAM"],"PIMPRI-CHINCHWAD":["PIMPRI-CHINCHWAD","PIMPRI CHINCHWAD","PCMC"],"PATNA":["PATNA","PATALIPUTRA"],"VADODARA":["VADODARA","BARODA"],"GHAZIABAD":["GHAZIABAD","GHZ"],"LUDHIANA":["LUDHIANA"],"AGRA":["AGRA"],"NASHIK":["NASHIK","NASIK"],"FARIDABAD":["FARIDABAD"],"MEERUT":["MEERUT"],"RAJKOT":["RAJKOT"],"KALYAN-DOMBIVLI":["KALYAN-DOMBIVLI","KALYAN","DOMBIVLI"],"VASAI-VIRAR":["VASAI-VIRAR","VASAI","VIRAR"],"VARANASI":["VARANASI","BANARAS","BENARES","KASHI"],"SRINAGAR":["SRINAGAR"],"AURANGABAD":["AURANGABAD"],"DHANBAD":["DHANBAD"],"AMRITSAR":["AMRITSAR"],"NAVI MUMBAI":["NAVI MUMBAI","NEW BOMBAY"],"ALLAHABAD":["ALLAHABAD","PRAYAGRAJ","ILAHABAD"],"RANCHI":["RANCHI"],"HOWRAH":["HOWRAH","HAORA"],"COIMBATORE":["COIMBATORE"],"JABALPUR":["JABALPUR","JUBBULPORE"],"GWALIOR":["GWALIOR"],"VIJAYAWADA":["VIJAYAWADA"],"JODHPUR":["JODHPUR"],"MADURAI":["MADURAI"],"RAIPUR":["RAIPUR"],"KOTA":["KOTA"],"GUWAHATI":["GUWAHATI","GAUHATI"],"CHANDIGARH":["CHANDIGARH","MOHALI","SAS NAGAR","KHARAR","PANCHKULA","ZIRAKPUR"],"SOLAPUR":["SOLAPUR","SHOLAPUR"],"HUBLI-DHARWAD":["HUBLI-DHARWAD","HUBLI","DHARWAD"],"BAREILLY":["BAREILLY"],"MORADABAD":["MORADABAD"],"MYSORE":["MYSORE","MYSURU"],"GURGAON":["GURGAON","GURUGRAM"],"ALIGARH":["ALIGARH"],"JALANDHAR":["JALANDHAR"],"TIRUCHIRAPPALLI":["TIRUCHIRAPPALLI","TRICHY","TRICHINOPOLY"],"BHUBANESWAR":["BHUBANESWAR","BHUBANESHWAR"],"SALEM":["SALEM"],"WARANGAL":["WARANGAL"],"THIRUVANANTHAPURAM":["THIRUVANANTHAPURAM","TRIVANDRUM"],"GUNTUR":["GUNTUR"],"BHIWANDI":["BHIWANDI"],"SAHARANPUR":["SAHARANPUR"],"GORAKHPUR":["GORAKHPUR"],"BIKANER":["BIKANER"],"AMRAVATI":["AMRAVATI"],"NOIDA":["NOIDA"],"JAMSHEDPUR":["JAMSHEDPUR","TATANAGAR"],"BHILAI":["BHILAI","BHILAI NAGAR"],"CUTTACK":["CUTTACK"],"FIROZABAD":["FIROZABAD"],"KOCHI":["KOCHI","COCHIN"],"BHAVNAGAR":["BHAVNAGAR"],"DEHRADUN":["DEHRADUN","DEHRA DUN"],"DURGAPUR":["DURGAPUR"],"ASANSOL":["ASANSOL"],"NANDED":["NANDED"],"KOLHAPUR":["KOLHAPUR"],"AJMER":["AJMER"],"GULBARGA":["GULBARGA","KALABURAGI"],"JAMNAGAR":["JAMNAGAR"],"UJJAIN":["UJJAIN"],"LONI":["LONI"],"SILIGURI":["SILIGURI"],"JHANSI":["JHANSI"],"ULHASNAGAR":["ULHASNAGAR"],"NELLORE":["NELLORE"],"JAMMU":["JAMMU"],"SANGALI-MIRAJ-KUPWAD":["SANGALI-MIRAJ-KUPWAD","SANGALI","MIRAJ","KUPWAD"],"BELGAUM":["BELGAUM","BELAGAVI"],"MANGALORE":["MANGALORE","MANGALURU"],"AMBATTUR":["AMBATTUR"],"TIRUNELVELI":["TIRUNELVELI"],"MALEGAON":["MALEGAON"],"GREATER NOIDA":["GREATER NOIDA"]}
+
+STATE_MAPPING = {"ANDHRA PRADESH":["ANDHRA PRADESH","ANDHRAPRADESH","ANDHRA","AP","A.P","A.P.","AP STATE","IN-AP"],"ARUNACHAL PRADESH":["ARUNACHAL PRADESH","ARUNACHAL","AR","A.R","ARUNACHAL PRADESH STATE","IN-AR"],"ASSAM":["ASSAM","AS","A.S","ASSAM STATE","IN-AS"],"BIHAR":["BIHAR","BR","B.R","BIHAR STATE","IN-BR"],"CHHATTISGARH":["CHHATTISGARH","CHATTISGARH","CHHATISGARH","CG","C.G","CT","CHATTISGARH STATE","IN-CG"],"GOA":["GOA","GA","G.A","IN-GA"],"GUJARAT":["GUJARAT","GUJRAT","GUJARATH","GJ","G.J","IN-GJ"],"HARYANA":["HARYANA","HARIYANA","HR","H.R","IN-HR"],"HIMACHAL PRADESH":["HIMACHAL PRADESH","HIMACHAL","HP","H.P","H.P.","IN-HP"],"JHARKHAND":["JHARKHAND","JH","J.H","IN-JH"],"KARNATAKA":["KARNATAKA","KARNATAK","KARN","KA","K.A","MYSORE STATE","IN-KA"],"KERALA":["KERALA","KERALAM","KL","K.L","IN-KL"],"MADHYA PRADESH":["MADHYA PRADESH","MADHYAPRADESH","MADHYA","MP","M.P","M.P.","MP STATE","IN-MP"],"MAHARASHTRA":["MAHARASHTRA","MAHARASTRA","MAHA","MH","M.H","MAHARASHTRA STATE","IN-MH"],"MANIPUR":["MANIPUR","MN","M.N","IN-MN"],"MEGHALAYA":["MEGHALAYA","ML","M.L","IN-ML"],"MIZORAM":["MIZORAM","MZ","M.Z","IN-MZ"],"NAGALAND":["NAGALAND","NL","N.L","IN-NL"],"ODISHA":["ODISHA","ORISSA","OD","O.D","OR","O.R","ODISHA STATE","IN-OD"],"PUNJAB":["PUNJAB","PANJAB","PB","P.B","IN-PB"],"RAJASTHAN":["RAJASTHAN","RAJ","RJ","R.J","RAJASTHAN STATE","IN-RJ"],"SIKKIM":["SIKKIM","SK","S.K","IN-SK"],"TAMIL NADU":["TAMIL NADU","TAMILNADU","TAMIL","TN","T.N","T.N.","TAMILNADU STATE","IN-TN"],"TELANGANA":["TELANGANA","TELENGANA","TG","T.G","TS","T.S","TELANGANA STATE","IN-TS"],"TRIPURA":["TRIPURA","TR","T.R","IN-TR"],"UTTAR PRADESH":["UTTAR PRADESH","UTTARPRADESH","UTTAR","UP","U.P","U.P.","UP STATE","IN-UP"],"UTTARAKHAND":["UTTARAKHAND","UTTARANCHAL","UK","U.K","UA","UTTARAKHAND STATE","IN-UK"],"WEST BENGAL":["WEST BENGAL","WESTBENGAL","WB","W.B","W.B.","WEST BENGAL STATE","IN-WB"],"ANDAMAN AND NICOBAR ISLANDS":["ANDAMAN AND NICOBAR ISLANDS","ANDAMAN NICOBAR","ANDAMAN","NICOBAR","AN","A.N","A & N ISLANDS","IN-AN"],"CHANDIGARH":["CHANDIGARH","CH","C.H","IN-CH","MOHALI","SAS NAGAR","KHARAR","PANCHKULA","ZIRAKPUR"],"DADRA AND NAGAR HAVELI AND DAMAN AND DIU":["DADRA AND NAGAR HAVELI AND DAMAN AND DIU","DADRA NAGAR HAVELI","DAMAN DIU","DN","D.N","DNH","DD","IN-DH"],"DELHI":["DELHI","NEW DELHI","DL","D.L","NCT OF DELHI","NATIONAL CAPITAL TERRITORY OF DELHI","NORTH EAST DELHI","NORTH WEST DELHI","SOUTH EAST DELHI","SOUTH WEST DELHI","SEELAMPUR","SHAHDARA","DWARKA","ROHINI","PITAMPURA","KAROL BAGH","LAJPAT NAGAR","SAKET","JANAKPURI","MAYUR VIHAR","VASANT KUNJ","OKHLA","NOIDA","GREATER NOIDA","FARIDABAD","GHAZIABAD","GHZ","INDIRAPURAM","GURUGRAM","GURGAON","IN-DL"],"JAMMU AND KASHMIR":["JAMMU AND KASHMIR","JAMMU","KASHMIR","JK","J.K","J&K","JAMMU & KASHMIR","IN-JK"],"LADAKH":["LADAKH","LA","L.A","IN-LA"],"LAKSHADWEEP":["LAKSHADWEEP","LAKSHADWEEP ISLANDS","LD","L.D","IN-LD"],"PUDUCHERRY":["PUDUCHERRY","PONDICHERRY","PY","P.Y","IN-PY"]}
+
+ADDRESS_MAPPING = {"DIST":["DISTRICT","DIST","DST","DSTR","DT","ZILLA","JILLA","ZILA"],"TALUK":["TALUK","TAL","TALUKA","TQ","TEH","TEHS","TEHSIL","MANDAL","MD"],"VILLAGE":["VILLAGE","VILL","VIL","VLG","GRAMA","GRAM","GAON"],"CITY":["CITY","CTY","TOWN","TWN","NAGAR","NAG","PURAM","PURA"],"STATE":["STATE","ST","RAJYA","PRADESH"],"HOUSE":["HOUSE NO","H NO","H.NO","H-NO","H/NO","HNO","HOUSE NUMBER","HOUSE#","HOUSE NUM","PROPERTY NO","PROPERTY NUMBER","RESIDENCE NO","RES NO","H:NO","H.NO:","D:NO","D.NO:"],"HOUSE":["D NO","D.NO","D-NO","D/NO","DNO","DOOR NO","DOOR NUMBER"],"APT":["APARTMENT","APT","APT NO","APT NUMBER","APARTMENT NO","TOWER","TOWER NO","WING","PHASE","PHASE NO","RESIDENCY","RESIDENTIAL COMPLEX","HEIGHTS","ENCLAVE","APARTMENTS","SOCIETY","SOCIETY NO","CHS"],"BLDG":["BLDG","BLDG NO","BUILDING","BUILDING NO"],"BLOCK":["BLK","BLOCK","BLOCK NO"],"FLAT":["FLAT","FLAT NO","FLAT NUMBER","FLT","FLT NO","UNIT","UNIT NO","UNIT NUMBER","PORTION","PORTION NO","OFFICE NO","OFFICE NUMBER"],"SHOP":["SHOP NO","SHOP NUMBER"],"ROAD":["ROAD","RD","R D","MARG","MRG","PATH"],"STR":["STREET","ST","STR","GALI","GALLLI","LANE","LN","MARG","PATH","CIRCLE","CIR","SECTOR","SEC"],"LANE":["LANE","LN","BYLANE","CROSS","CR"],"EXTN":["EXTENSION","EXT","EXTN"],"LOCALITY":["LOCALITY","LAYOUT","LYT","PHASE","PH","SECTOR","SEC"],"CLNY":["COLONY","COL","CLNY"],"BUILDING":["BUILDING","APT","APARTMENT","BLDG","TOWER"]}
+
+
+[IDENTIFIERS]
+
+APARTMENT_IDENTIFIER=APT
+FLAT_NUMBER_IDENTIFIER=FLAT
+HOUSE_NUMBER_IDENTIFIER= HOUSE
+STREET_KEYWORD=STR
+FLOOR_KEYWORD=FLR
+DOOR_NO_KEYWORD=DOOR
+INDIAN_SURNAMES = ["SINGH","THAKUR","RAJPUT","SHARMA","PANDEY","PANDE","PANDAY","MISHRA","TIWARI","TRIPATHI","DWIVEDI","AWASTHI","GUPTA","AGARWAL","AGGARWAL","BANSAL","GOYAL","MITTAL","VERMA","SAXENA","SRIVASTAVA","NIGAM","RASTOGI","MALHOTRA","KHANNA","ARORA","BHATIA","KOHLI","OBEROI","CHAUDHARY","CHOUDHARY","CHOWDHARY","CHOWDARY","PATEL","SHAH","MEHTA","PANDYA","TRIVEDI","DAVE","DESAI","PAREKH","JOSHI","BHATT","VORA","MODI","KULKARNI","DESHPANDE","APTE","CHITNIS","GOKHALE","PHADKE","NAIK","PAWAR","JADHAV","SHINDE","SAWANT","REDDY","REDDAPPA","REDDIGARI","RAO","NAIDU","RAJU","VARMA","SASTRY","SHASTRI","GOUD","CHOWDARY","CHOUDARY","SETTY","SHETTY","GOWDA","HEGDE","BHAT","PAI","KAMATH","SHENOY","PRABHU","NAYAK","SHETTY","IYER","IYENGAR","AYYAR","PILLAI","MUDALIAR","THEVAR","GOUNDER","CHETTIAR","NADAR","KANNAN","KRISHNAN","RAMAN","SUBRAMANIAN","NAIR","MENON","PILLAI","KURUP","PANICKER","VARMA","NAMBOOTHIRI","NAMBIAR","CHACKO","MATHEW","THOMAS","VARGHESE","DAS","DUTTA","BANERJEE","MUKHERJEE","CHATTERJEE","GHOSH","BOSE","SEN","ROY","SARKAR","MONDAL","MALLICK","MOHANTY","DASH","SAHOO","PATNAIK","NAYAK","PANDA","MUNDA","ORAON","TOPPO","TIRKEY","EKKA","MINZ","YADAV","SAHU","RATHORE","BAGHEL","LODHI","KUSHWAHA","THAKUR","BARUAH","BARUA","GOGOI","SAIKIA","DEKA","HAZARIKA","SANGMA","MARAK","LYNGDOH","LALLAWMA","LALTHANGLIANA","AO","SEMA","KONYAK","SHIMRAY","NINGOMBAM","ALI","HASSAN","KOYA","JAIN","MALIK","SINGHAL","AMBEDKAR","CHAMAR","PANDIT","KAPOOR","CHOPRA","MALIK","SINGHAL","JAIN","PADUKONE"]
+
+
+
+[csv]
+name_variation_standard = data/name_variation_standard.csv
+hno_variation_standard = data/hno_variation_standard.csv
+city_prev_pres = data/city_prev_pres.csv
+state_name_standard = data/state_name_standard.csv
+sur_comm_names = data/sur_comm_names.csv
+pin_city_state = data/pin_city_state.csv
+
+[MATCHING_LOGIC]
+MODEL_WEIGHTS = {
+    "simple_ratio": 0.0,
+    "token_set_ratio": 0.0,
+    "partial_ratio": 0.1,
+    "w_ratio": 0.1,
+    "semantic_score": 0.8
+    }
+
+MATCHING_RULES = [
+        
+        ([("NAME", 100), ("ZIPCODE", 100), ("ADDRESSLINE", 65)], "NAME >= 100 AND ZIPCODE >= 100 AND ADDRESS >= 65"),
+        ([("NAME", 100), ("CITY", 100), ("ADDRESSLINE", 65)], "NAME >= 100 AND CITY >= 100 AND ADDRESS >= 65"),
+        ([("NAME", 85), ("LASTNAME", 85), ("BIRTHDATE", 100), ("ADDRESSLINE", 60)], "NAME >= 85 AND LASTNAME >= 85 AND DOB >= 100 AND ADDRESS >= 60"),
+        ([("NAME", 85), ("BIRTHDATE", 100), ("ZIPCODE", 100)], "NAME >= 85 AND DOB >= 100 AND ZIPCODE >= 100"),
+        ([("NAME", 85), ("BIRTHDATE", 100), ("CITY", 100)], "NAME >= 85 AND DOB >= 100 AND CITY >= 100"),
+        ([("NAME", 85), ("ZIPCODE", 100), ("ADDRESSLINE", 60)], "NAME >= 85 AND ZIPCODE >= 100 AND ADDRESS >= 60"),
+        ([("NAME", 85), ("CITY", 100), ("ADDRESSLINE", 60)], "NAME >= 85 AND CITY >= 100 AND ADDRESS >= 60"),
+        ([("BIRTHDATE", 100), ("ZIPCODE", 100), ("ADDRESSLINE", 65)], "BIRTHDATE >= 100 AND ZIPCODE >= 100 AND ADDRESS >= 65"),
+        ([("BIRTHDATE", 100), ("CITY", 100), ("ADDRESSLINE", 65)], "BIRTHDATE >= 100 AND CITY >= 100 AND ADDRESS >= 65"),
+        ([("LASTNAME", 85), ("ZIPCODE", 100), ("ADDRESSLINE", 60)], "LASTNAME >= 85 AND ZIPCODE >= 100 AND ADDRESS >= 60"),
+        ([("NAME", 85), ("PHONE", 100)], "NAME >= 85 AND PHONE >= 100"),
+        ([("BIRTHDATE", 100), ("PHONE", 100)], "BIRTHDATE >= 100 AND PHONE >= 100"),
+        ([("BIRTHDATE", 100), ("NAME", 85)], "BIRTHDATE >=100 AND NAME>=85"),
+        ([("ADDRESSLINE", 60), ("TAXID", 100)], "ADDRESS >= 60 and PAN >= 100"),
+        ([("ADDRESSLINE", 60), ("LICENSEID", 100)], "ADDRESS >= 60 and DRIVING_LICN_NO >= 100"),
+        ([("BIRTHDATE", 75), ("PHONE", 100)], "BIRTHDATE >= 75 and PHONE >= 100"),
+        ([("BIRTHDATE", 75), ("TAXID", 100)], "BIRTHDATE >= 75 and PAN >= 100"),
+        ([("BIRTHDATE", 75), ("LICENSEID", 100)], "BIRTHDATE >= 75 and DRIVING_LICN_NO >= 100"),
+        ([("BIRTHDATE", 75), ("PASSPORTID", 100)], "BIRTHDATE >= 75 and PASSPORT_NO >= 100"),
+        ([("NAME", 60), ("PASSPORTID", 100)], "NAME >= 60 and PASSPORT_NO >= 100"),
+        ([("NAME", 60), ("LICENSEID", 100)], "NAME >= 60 and DRIVING_LICN_NO >= 100"),
+        ([("NAME", 60), ("TAXID", 100)], "NAME >= 60 and AADHAR >= 100"),
+        ([("NAME", 60), ("AADHAR", 100)], "NAME >= 60 and AADHAR >= 100"),
+        ([("NAME", 60), ("PAN", 100)], "NAME >= 60 and PAN >= 100"),
+        ([("PHONE", 100)], "PHONE >= 100"),
+        ([("LICENSEID", 100)], "DRIVING_LICN_NO >= 100"),
+        ([("PASSPORTID", 100)], "PASSPORT_NO >= 100"),
+        ([("TAXID", 100)], "AADHAR >= 100"),
+        ([("AADHAR", 100)], "AADHAR >= 100"),
+        ([("PAN", 100)], "PAN >= 100"),
+        ([("EMAIL", 100)], "EMAIL >= 100")
+    ]
+
+
+
+[NAME_MATCHING]
+NAME_MODEL_WEIGHTS = {
+    "simple_ratio": 0.04,
+    "token_set_ratio": 0.04,
+    "partial_ratio": 0.04,
+    "w_ratio": 0.04,
+    "token_sort_ratio": 0.04,
+    "semantic_score": 0.7,
+    "jaro_winkler": 0.05,
+    "indic_soundex": 0.05
+    }
+
+NAME_MATCH_ADJUSTMENTS = {
+    "surname_penalty": -20,
+    "initial_boost": 20,
+    "subset_boost": 20
+    }
+
+[ADDRESS_MATCHING]
+ADDRESS_MODEL_WEIGHTS = {
+    "simple_ratio": 0.04,
+    "token_set_ratio": 0.04,
+    "partial_ratio": 0.04,
+    "w_ratio": 0.04,
+    "token_sort_ratio": 0.04,
+    "semantic_score": 0.8
+    }
+
+ADDRESS_MATCH_ADJUSTMENTS = {
+    "house_match_boost": 30,
+    "house_mismatch_penalty": 70
+    }
+
+[EMBEDDING_MODELS]
+MODEL_1_NAME = BAAI/bge-small-en-v1.5
+MODEL_2_NAME = sentence-transformers/gtr-t5-base

backend/matching_service.py

@@ -0,0 +1,683 @@
+import sys
+import os
+import time
+import logging
+from typing import Dict, Any, Optional, Tuple, Union
+
+# Ensure project root is on sys.path so sibling modules resolve
+_PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+import numpy as np
+import pandas as pd
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from services.config import (
+    config,
+    pin_city_state_df,
+    ADDRESS_MATCH_ADJUSTMENTS,
+)
+
+from services.rules import (
+    preprocess_text,
+    standardize_column,
+    standardize_city,
+    standardize_state,
+    standardize_dob,
+    compare_exact,
+    compare_any_match,
+    compare_phone_any_match,
+    compare_email_any_match,
+    evaluate_matching_rules,
+   
+    apply_pattern_matching_logic,
+    pincode_similarity_india,
+    extract_address_components,
+    validate_and_normalize_phone,
+    validate_and_normalize_email,
+    validate_and_normalize_pan,
+    validate_and_normalize_aadhar,
+    preprocess_name,
+    detect_surnames,
+    compute_initial_letter_boost,
+    clean_text,
+    deduplicate_tokens,
+    deduplicate_consecutive_tokens,
+    strip_non_alphanumeric,
+)
+
+from services.model import (
+    match_names_cross_records as embedding_match_names,
+    match_single_field as embedding_match_single,
+)
+from services.address_matcher import match_addresses_enhanced
+
+
+
+logger = logging.getLogger("matching_service")
+
+# =========================================================
+# SENTINEL
+# =========================================================
+_MISSING = -1  # internal sentinel for "field not provided"
+
+
+# =========================================================
+# HELPERS
+# =========================================================
+def _is_valid_value(val: Any) -> bool:
+    if val is None:
+        return False
+    s = str(val).strip().lower()
+    return s not in ("", "-", " ", "na", "n/a", "null", "none", "missing value", "missing")
+
+
+def _clean_input(val: str) -> str:
+    """Convert placeholder strings to empty string."""
+    if not val:
+        return ""
+    if val.strip().lower() in ("missing value", "missing", "na", "n/a", "null", "none"):
+        return ""
+    return val
+
+
+def _is_field_empty(val: Any) -> bool:
+    return not _is_valid_value(val)
+
+
+def _normalize_gender(val: Any) -> Optional[str]:
+    """Normalize gender values to canonical MALE / FEMALE / OTHER."""
+    if not _is_valid_value(val):
+        return None
+    s = str(val).strip().lower()
+    if s in ("m", "male", "men", "man"):
+        return "MALE"
+    if s in ("f", "female", "women", "woman"):
+        return "FEMALE"
+    return s.upper()
+
+
+def _safe_round(val: Any) -> float:
+    try:
+        v = round(float(val), 2)
+        return max(v, 0.0)
+    except (ValueError, TypeError):
+        return 0.0
+
+
+# =========================================================
+# FLATTEN: EntityRecord → flat dict
+# =========================================================
+def flatten_entity_record(record) -> Dict[str, Any]:
+    """
+    Convert an backend.models.EntityRecord (structured, nested) into the flat
+    dictionary format that match_structured_records() expects.
+
+    Mapping:
+        addresses[0] → addressline_0, city_0, state_0, zipcode_0
+        addresses[1] → addressline_1, city_1, state_1, zipcode_1
+        addresses[N] → addressline_N, city_N, state_N, zipcode_N   ← N entries
+        phones[0]    → phone_0
+        phones[1]    → phone_1                                      ← N entries
+        emails[0]    → email_0
+        emails[1]    → email_1                                      ← N entries
+        custom_fields → top-level keys (uppercase)
+
+    The downstream match_structured_records() function picks up all these
+    indexed keys via get_dynamic_fields() and runs best-of-N / any-match
+    comparisons automatically — no changes needed there.
+    """
+    flat: Dict[str, Any] = {
+        "name":              _clean_input(record.name),
+        "firstname":         _clean_input(record.firstname),
+        "middlename":        _clean_input(record.middlename),
+        "lastname":          _clean_input(record.lastname),
+        "mothername":        _clean_input(record.mothername),
+        "fathername":        _clean_input(record.fathername),
+        "spousename":        _clean_input(record.spousename),
+        "othername":         _clean_input(record.othername),
+        "dob":               _clean_input(record.dob),
+        "gender":            _clean_input(record.gender),
+        "AADHAR":            _clean_input(record.aadhar),
+        "pan":               _clean_input(record.pan),
+        "licenseid":         _clean_input(record.licenseid),
+        "passportid":        _clean_input(record.passportid),
+        "voterid":           _clean_input(record.voterid),
+        "companyname":       _clean_input(record.companyname),
+        "parentcompanyname": _clean_input(record.parentcompanyname),
+    }
+
+    # ── Addresses → addressline_0, city_0, …, addressline_N, city_N, … ──
+    # models.py already deduplicates and removes blank entries before we
+    # get here, so record.addresses contains only meaningful addresses.
+    for idx, addr in enumerate(record.addresses):
+        flat[f"addressline_{idx}"] = _clean_input(addr.addressline)
+        flat[f"city_{idx}"]        = _clean_input(addr.city)
+        flat[f"state_{idx}"]       = _clean_input(addr.state)
+        flat[f"zipcode_{idx}"]     = _clean_input(addr.zipcode)
+
+    # ── Phones → phone_0, phone_1, … ─────────────────────────────────────
+    # models.py already deduplicates and removes placeholder entries.
+    for idx, phone in enumerate(record.phones):
+        flat[f"phone_{idx}"] = phone
+
+    # ── Emails → email_0, email_1, … ─────────────────────────────────────
+    for idx, email in enumerate(record.emails):
+        flat[f"email_{idx}"] = email
+
+    # ── Custom fields → top-level keys ───────────────────────────────────
+    for key, value in record.custom_fields.items():
+        safe_key = str(key).strip()
+        if safe_key:
+            flat[safe_key] = value
+
+    logger.debug(
+        "flatten_entity_record → %d addresses, %d phones, %d emails",
+        len(record.addresses), len(record.phones), len(record.emails),
+    )
+    return flat
+
+
+# =========================================================
+# STANDARDIZE: apply preprocessing pipeline to a flat dict
+# =========================================================
+def standardize_record(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Apply the full standardization pipeline to a flat record dict.
+    Mirrors the logic from app_streamlit.py main() lines 1434-1512.
+
+    Dynamic fields (addressline_N, city_N, state_N, zipcode_N, phone_N,
+    email_N) are handled by the loop at the bottom — no changes needed
+    for multi-value support.
+    """
+    processed: Dict[str, Any] = {
+        "gender":            preprocess_text(raw.get("gender", "")),
+        "name":              preprocess_name(raw.get("name", "")),
+        "firstname":         preprocess_name(raw.get("firstname", "")),
+        "middlename":        preprocess_name(raw.get("middlename", "")),
+        "lastname":          preprocess_name(raw.get("lastname", "")),
+        "spousename":        preprocess_name(raw.get("spousename", "")),
+        "mothername":        preprocess_name(raw.get("mothername", "")),
+        "fathername":        preprocess_name(raw.get("fathername", "")),
+        "companyname":       standardize_column(raw.get("companyname", ""), "companyname"),
+        "parentcompanyname": standardize_column(raw.get("parentcompanyname", ""), "parentcompanyname"),
+        "AADHAR":            standardize_column(raw.get("AADHAR", ""), "AADHAR"),
+        "pan":               standardize_column(raw.get("pan", ""), "pan"),
+        "licenseid":         standardize_column(raw.get("licenseid", ""), "licenseid"),
+        "passportid":        standardize_column(raw.get("passportid", ""), "passportid"),
+        "voterid":           standardize_column(raw.get("voterid", ""), "voterid"),
+        "dob":               standardize_dob(raw.get("dob", "")),
+    }
+
+    # ── Dynamic fields — handle all N entries automatically ──────────────
+    for key, value in raw.items():
+        if key.startswith("addressline_"):
+            processed[key] = standardize_column(raw.get(key, ""), "addressline")
+        elif key.startswith("city_"):
+            processed[key] = standardize_city(value) if _is_valid_value(value) else None
+        elif key.startswith("zipcode_"):
+            processed[key] = standardize_column(raw.get(key, ""), key)
+        elif key.startswith("state_"):
+            processed[key] = standardize_state(value) if _is_valid_value(value) else None
+        elif key.startswith("phone_"):
+            processed[key] = standardize_column(raw.get(key, ""), key)
+        elif key.startswith("email_"):
+            processed[key] = standardize_column(raw.get(key, ""), key)
+        elif key not in processed:
+            # Custom fields — keep uppercase keys
+            safe_key = str(key).strip()
+            if safe_key:
+                processed[safe_key.upper()] = value
+
+    return processed
+
+
+
+
+
+# =========================================================
+# MATCH STRUCTURED RECORDS
+# Extracted from app_streamlit.py lines 912-1250
+# =========================================================
+def match_structured_records(
+    r1: Dict[str, Any],
+    r2: Dict[str, Any],
+    mode: str = "embedding",
+) -> Dict[str, Any]:
+    """
+    Core matching engine.  Accepts two *standardized* flat record dicts.
+    Returns a dict of field → score.
+
+    Multi-value handling (all already in place — no changes needed):
+        ─ Addresses : get_dynamic_fields("addressline_") collects all N
+                      addresslines from both records; embedding_match_addresses
+                      run best-of-N across all combos.
+        ─ Phones    : get_dynamic_fields("phone_") + compare_phone_any_match
+                      — any-match across all phone combinations.
+        ─ Emails    : get_dynamic_fields("email_") + compare_email_any_match
+                      — any-match across all email combinations.
+        ─ City/State/Zipcode: cross-compared across all pincode combinations
+                      via the nested loop (i, j) — already handles N pincodes.
+    """
+
+    # ── helpers (closures) ──────────────────────────────────────────────
+    def get_dynamic_fields(record: Dict, prefix: str):
+        """
+        Extract all dynamic fields with given prefix from record.
+        Works for any N: phone_0, phone_1, …, phone_N.
+        """
+        fields = []
+        i = 0
+        while True:
+            key = f"{prefix}{i}"
+            if key in record:
+                fields.append(record.get(key))
+                i += 1
+            else:
+                break
+        return fields
+
+    def lookup_pincode_df(pincode, df):
+        if not _is_valid_value(pincode):
+            return None, None
+        row = df.loc[df["pincode"].astype(str) == str(pincode)]
+        if not row.empty:
+            return row.iloc[0]["districtname"], row.iloc[0]["statename"]
+        return None, None
+
+    # ── geo / pincode enrichment ─────────────────────────────────────────
+    city_match    = 0
+    state_match   = 0
+    zipcode_match = 0
+
+    pincode_match_found = False
+    best_pincode_score  = 0
+
+    # Use pre-loaded CSV DataFrame instead of MySQL
+    pincode_df = pin_city_state_df
+
+    r1_pincodes    = get_dynamic_fields(r1, "zipcode_")
+    r2_pincodes    = get_dynamic_fields(r2, "zipcode_")
+    r1_cities_user = get_dynamic_fields(r1, "city_")
+    r2_cities_user = get_dynamic_fields(r2, "city_")
+    r1_states_user = get_dynamic_fields(r1, "state_")
+    r2_states_user = get_dynamic_fields(r2, "state_")
+
+    r1_cities, r2_cities = [], []
+    r1_states, r2_states = [], []
+
+    # Cross-compare ALL pincode combinations (i × j) — handles N pincodes
+    for i, r1_pincode in enumerate(r1_pincodes):
+        for j, r2_pincode in enumerate(r2_pincodes):
+            r1_city_user  = r1_cities_user[i]  if i < len(r1_cities_user)  else None
+            r2_city_user  = r2_cities_user[j]  if j < len(r2_cities_user)  else None
+            r1_state_user = r1_states_user[i]  if i < len(r1_states_user)  else None
+            r2_state_user = r2_states_user[j]  if j < len(r2_states_user)  else None
+
+            if _is_valid_value(r1_pincode) and _is_valid_value(r2_pincode):
+                # --- CSV lookup first ---
+                r1_city_df,  r1_state_df  = lookup_pincode_df(r1_pincode, pincode_df)
+                r2_city_df,  r2_state_df  = lookup_pincode_df(r2_pincode, pincode_df)
+
+                # --- Pincode similarity (for scoring) ---
+                if r1_pincode == r2_pincode:
+                    pincode_match_found = True
+                    best_pincode_score  = max(best_pincode_score, 100)
+                else:
+                    # Different pincodes — pincode score = 0 (exact match or nothing)
+                    pass
+
+                # --- City/State enrichment: prefer CSV, then pgeocode fallback ---
+                got_r1_geo = bool(r1_city_df and r1_state_df)
+                got_r2_geo = bool(r2_city_df and r2_state_df)
+
+                if got_r1_geo:
+                    r1_cities.append(standardize_city(r1_city_df))
+                    r1_states.append(standardize_state(r1_state_df))
+                if got_r2_geo:
+                    r2_cities.append(standardize_city(r2_city_df))
+                    r2_states.append(standardize_state(r2_state_df))
+
+                # pgeocode fallback for any pin not found in CSV
+                got_r1_pgeo = False
+                got_r2_pgeo = False
+                if not got_r1_geo or not got_r2_geo:
+                    pin_result = pincode_similarity_india(r1_pincode, r2_pincode)
+                    if not got_r1_geo:
+                        if pin_result.get("pin1_county_name"):
+                            r1_cities.append(standardize_city(pin_result["pin1_county_name"]))
+                            got_r1_pgeo = True
+                        if pin_result.get("pin1_state_name"):
+                            r1_states.append(standardize_state(pin_result["pin1_state_name"]))
+                            got_r1_pgeo = True
+                    if not got_r2_geo:
+                        if pin_result.get("pin2_county_name"):
+                            r2_cities.append(standardize_city(pin_result["pin2_county_name"]))
+                            got_r2_pgeo = True
+                        if pin_result.get("pin2_state_name"):
+                            r2_states.append(standardize_state(pin_result["pin2_state_name"]))
+                            got_r2_pgeo = True
+
+                # If STILL no geo for a pin, fall back to user-entered city/state
+                if not got_r1_geo and not got_r1_pgeo:
+                    if _is_valid_value(r1_city_user):
+                        r1_cities.append(standardize_city(r1_city_user))
+                    if _is_valid_value(r1_state_user):
+                        r1_states.append(standardize_state(r1_state_user))
+                if not got_r2_geo and not got_r2_pgeo:
+                    if _is_valid_value(r2_city_user):
+                        r2_cities.append(standardize_city(r2_city_user))
+                    if _is_valid_value(r2_state_user):
+                        r2_states.append(standardize_state(r2_state_user))
+            else:
+                if _is_valid_value(r1_city_user):
+                    r1_cities.append(standardize_city(r1_city_user))
+                if _is_valid_value(r2_city_user):
+                    r2_cities.append(standardize_city(r2_city_user))
+                if _is_valid_value(r1_state_user):
+                    r1_states.append(standardize_state(r1_state_user))
+                if _is_valid_value(r2_state_user):
+                    r2_states.append(standardize_state(r2_state_user))
+
+    # Fallback: user-entered cities/states if no pincodes provided
+    if not r1_pincodes or not r2_pincodes:
+        for city_val in r1_cities_user:
+            if _is_valid_value(city_val) and standardize_city(city_val) not in r1_cities:
+                r1_cities.append(standardize_city(city_val))
+        for city_val in r2_cities_user:
+            if _is_valid_value(city_val) and standardize_city(city_val) not in r2_cities:
+                r2_cities.append(standardize_city(city_val))
+        for state_val in r1_states_user:
+            if _is_valid_value(state_val) and standardize_state(state_val) not in r1_states:
+                r1_states.append(standardize_state(state_val))
+        for state_val in r2_states_user:
+            if _is_valid_value(state_val) and standardize_state(state_val) not in r2_states:
+                r2_states.append(standardize_state(state_val))
+
+    # City / State / Pincode scoring
+    if r1_cities and r2_cities:
+        if any(c1 == c2 for c1 in r1_cities for c2 in r2_cities):
+            city_match = 100
+        elif pincode_match_found:
+            city_match = 100
+
+    if r1_states and r2_states:
+        if any(s1 == s2 for s1 in r1_states for s2 in r2_states):
+            state_match = 100
+
+    zipcode_match = compare_any_match(r1_pincodes, r2_pincodes, field_type="pincode")
+
+    # ── Phone / Email matching ───────────────────────────────────────────
+    # compare_phone_any_match / compare_email_any_match already handle
+    # lists of any length — any-match strategy.
+    r1_phones = get_dynamic_fields(r1, "phone_")
+    r2_phones = get_dynamic_fields(r2, "phone_")
+    phone_match = compare_phone_any_match(r1_phones, r2_phones)
+
+    r1_emails = get_dynamic_fields(r1, "email_")
+    r2_emails = get_dynamic_fields(r2, "email_")
+    email_match = compare_email_any_match(r1_emails, r2_emails)
+
+    logger.debug(
+        "match_structured_records — phones R1=%s R2=%s | emails R1=%s R2=%s | "
+        "addresses R1=%d R2=%d",
+        r1_phones, r2_phones, r1_emails, r2_emails,
+        len(get_dynamic_fields(r1, "addressline_")),
+        len(get_dynamic_fields(r2, "addressline_")),
+    )
+
+    # ── Name / Address / Single-field matching (mode-dependent) ─────────
+   
+    name_match = embedding_match_names(
+        r1.get("name"), r1.get("firstname"), r1.get("lastname"), r1.get("middlename"),
+        r2.get("name"), r2.get("firstname"), r2.get("lastname"), r2.get("middlename"),
+    )
+
+    r1_addrs = get_dynamic_fields(r1, "addressline_")
+    r2_addrs = get_dynamic_fields(r2, "addressline_")
+
+    # ── Enhanced address matching with full pipeline ──
+    address_match = match_addresses_enhanced(r1_addrs, r2_addrs)
+
+    spousename_match        = embedding_match_single(r1.get("spousename"),        r2.get("spousename"))
+    mothername_match        = embedding_match_single(r1.get("mothername"),         r2.get("mothername"))
+    fathername_match        = embedding_match_single(r1.get("fathername"),         r2.get("fathername"))
+    companyname_match       = embedding_match_single(r1.get("companyname"),        r2.get("companyname"))
+    parentcompanyname_match = embedding_match_single(r1.get("parentcompanyname"),  r2.get("parentcompanyname"))
+
+    # ── Exact matching ───────────────────────────────────────────────────
+    g1 = _normalize_gender(r1.get("gender"))
+    g2 = _normalize_gender(r2.get("gender"))
+    if not g1 and not g2:
+        gender_match = ""
+    elif g1 and g2 and g1 == g2:
+        gender_match = 100
+    else:
+        gender_match = 0
+
+    aadhar_match     = compare_exact(r1.get("AADHAR"),     r2.get("AADHAR"))
+    pan_match        = compare_exact(r1.get("pan"),        r2.get("pan"))
+    licenseid_match  = compare_exact(r1.get("licenseid"),  r2.get("licenseid"))
+    passportid_match = compare_exact(r1.get("passportid"), r2.get("passportid"))
+    voterid_match    = compare_exact(r1.get("voterid"),    r2.get("voterid"))
+    dob_match        = compare_exact(r1.get("dob"),        r2.get("dob"))
+
+    # ── Assemble results ─────────────────────────────────────────────────
+    results = {
+        "GENDER":           apply_pattern_matching_logic("GENDER",           gender_match)           if gender_match           != "" else _MISSING,
+        "NAME":             name_match["full_name_percent"]                                          if name_match is not None  else _MISSING,
+        "FIRSTNAME":        name_match["firstname_percent"]                                          if name_match is not None  else _MISSING,
+        "MIDDLENAME":       name_match["middlename_percent"]                                         if name_match is not None  else _MISSING,
+        "LASTNAME":         name_match["lastname_percent"]                                           if name_match is not None  else _MISSING,
+        "SPOUSENAME":       apply_pattern_matching_logic("SPOUSENAME",       spousename_match)       if spousename_match       != "" else _MISSING,
+        "MOTHERNAME":       apply_pattern_matching_logic("MOTHERNAME",       mothername_match)       if mothername_match       != "" else _MISSING,
+        "FATHERNAME":       apply_pattern_matching_logic("FATHERNAME",       fathername_match)       if fathername_match       != "" else _MISSING,
+        "COMPANYNAME":      apply_pattern_matching_logic("COMPANYNAME",      companyname_match)      if companyname_match      != "" else _MISSING,
+        "PARENTCOMPANYNAME":apply_pattern_matching_logic("PARENTCOMPANYNAME",parentcompanyname_match)if parentcompanyname_match!= "" else _MISSING,
+        "AADHAR":           apply_pattern_matching_logic("AADHAR",           aadhar_match)           if aadhar_match           != "" else _MISSING,
+        "PAN":              apply_pattern_matching_logic("PAN",              pan_match)              if pan_match              != "" else _MISSING,
+        "LICENSEID":        apply_pattern_matching_logic("LICENSEID",        licenseid_match)        if licenseid_match        != "" else _MISSING,
+        "PASSPORTID":       apply_pattern_matching_logic("PASSPORTID",       passportid_match)       if passportid_match       != "" else _MISSING,
+        "VOTERID":          apply_pattern_matching_logic("TAXID",            voterid_match)          if voterid_match          != "" else _MISSING,
+        "ADDRESSLINE":      apply_pattern_matching_logic("ADDRESSLINE",      address_match)          if address_match          != "" else _MISSING,
+        "BIRTHDATE":        apply_pattern_matching_logic("BIRTHDATE",        dob_match)              if dob_match              != "" else _MISSING,
+        "PHONE":            apply_pattern_matching_logic("PHONE",            phone_match)            if phone_match            != "" else _MISSING,
+        "EMAIL":            apply_pattern_matching_logic("EMAIL",            email_match)            if email_match            != "" else _MISSING,
+        "CITY":             apply_pattern_matching_logic("CITY",             city_match)             if city_match             != "" else _MISSING,
+        "STATE":            apply_pattern_matching_logic("STATE",            state_match)            if state_match            != "" else _MISSING,
+        "ZIPCODE":          apply_pattern_matching_logic("ZIPCODE",          zipcode_match)          if zipcode_match          != "" else _MISSING,
+    }
+
+    # ── Custom field matching ────────────────────────────────────────────
+    known_keys = {
+        "name", "firstname", "middlename", "lastname", "spousename",
+        "mothername", "fathername", "dob", "gender", "AADHAR", "pan",
+        "licenseid", "passportid", "voterid", "companyname", "parentcompanyname",
+    }
+    all_keys = set(r1.keys()) | set(r2.keys())
+    for key in all_keys:
+        key_str = str(key)
+        if key_str in known_keys:
+            continue
+        if any(key_str.startswith(p) for p in (
+            "zipcode_", "city_", "state_", "phone_", "email_", "addressline_"
+        )):
+            continue
+        val1 = r1.get(key) or r1.get(key_str.upper())
+        val2 = r2.get(key) or r2.get(key_str.upper())
+        if val1 or val2:
+            score = compare_exact(val1, val2)
+            results[key_str.upper()] = score
+
+    return results
+
+
+# =========================================================
+# FORMAT RESULTS
+# =========================================================
+def format_results(
+    field_results: Dict[str, Any],
+    r1_processed: Dict[str, Any],
+    r2_processed: Dict[str, Any],
+    mode: str,
+) -> Dict[str, Any]:
+    """
+    Convert raw field scores into the final response format.
+    Handles 'missing value' detection and mode-specific formatting.
+
+    Dynamic prefixes (addressline_, phone_, email_, city_, state_, zipcode_)
+    are scanned from both processed records so missing-value detection works
+    correctly regardless of how many entries are present in each record.
+    
+    [MODIFIED 2026-03-15]
+    - Expanded 'field_to_inputs' mapping for NAME to explicitly check First, 
+      Middle, and Last name fields. This prevents `format_results` from blindly
+      overwriting a valid exact FML match score back to 'missing value'.
+    """
+
+    # Static field → input key mappings
+    field_to_inputs: Dict[str, list] = {
+        "GENDER":           [("gender",)],
+        "NAME":             [("name",), ("firstname",), ("middlename",), ("lastname",)],
+        "FIRSTNAME":        [("firstname",)],
+        "MIDDLENAME":       [("middlename",)],
+        "LASTNAME":         [("lastname",)],
+        "SPOUSENAME":       [("spousename",)],
+        "MOTHERNAME":       [("mothername",)],
+        "FATHERNAME":       [("fathername",)],
+        "COMPANYNAME":      [("companyname",)],
+        "PARENTCOMPANYNAME":[("parentcompanyname",)],
+        "AADHAR":           [("AADHAR",)],
+        "PAN":              [("pan",)],
+        "LICENSEID":        [("licenseid",)],
+        "PASSPORTID":       [("passportid",)],
+        "VOTERID":          [("voterid",)],
+        "BIRTHDATE":        [("dob",)],
+    }
+
+    # Dynamic field mappings — scan ALL keys from both records so N-entry
+    # fields are correctly represented regardless of how many were sent.
+    for prefix, result_key in [
+        ("addressline_", "ADDRESSLINE"),
+        ("phone_",       "PHONE"),
+        ("email_",       "EMAIL"),
+        ("city_",        "CITY"),
+        ("state_",       "STATE"),
+        ("zipcode_",     "ZIPCODE"),
+    ]:
+        input_keys = [
+            k for k in list(r1_processed.keys()) + list(r2_processed.keys())
+            if k.startswith(prefix)
+        ]
+        field_to_inputs[result_key] = [(k,) for k in input_keys] if input_keys else []
+
+    def check_missing(result_key: str) -> bool:
+        """
+        Return True only if BOTH records have no valid data for this field.
+        For multi-value fields, any single valid value in either record means
+        the field is NOT missing.
+        """
+        input_defs = field_to_inputs.get(result_key)
+        if input_defs is None:
+            return field_results.get(result_key) == _MISSING
+        if not input_defs:
+            return True
+            
+        # For CITY and STATE, consider them present if ZIPCODE was provided,
+        # because the backend infers city/state from the zipcode.
+        if result_key in ["CITY", "STATE"]:
+            zipcode_defs = field_to_inputs.get("ZIPCODE", [])
+            for (field_key,) in zipcode_defs:
+                r1_val = r1_processed.get(field_key)
+                r2_val = r2_processed.get(field_key)
+                if not _is_field_empty(r1_val) or not _is_field_empty(r2_val):
+                    return False
+
+        for (field_key,) in input_defs:
+            r1_val = r1_processed.get(field_key)
+            r2_val = r2_processed.get(field_key)
+            if not _is_field_empty(r1_val) or not _is_field_empty(r2_val):
+                return False
+        return True
+
+    formatted_scores: Dict[str, Any] = {}
+    all_keys = list(field_to_inputs.keys())
+
+    for k in all_keys:
+        v = field_results.get(k, _MISSING)
+
+        if check_missing(k):
+            formatted_scores[k] = "missing value"
+        elif mode == "embedding":
+            if v == _MISSING:
+                formatted_scores[k] = "missing value"
+            else:
+                try:
+                    formatted_scores[k] = _safe_round(v)
+                except (ValueError, TypeError):
+                    formatted_scores[k] = "missing value"
+        else:
+            if v == _MISSING:
+                formatted_scores[k] = 0.0
+            else:
+                formatted_scores[k] = _safe_round(v)
+
+    return formatted_scores
+
+
+# =========================================================
+# PUBLIC backend — single match
+# =========================================================
+def perform_match(record1, record2, mode: str = "embedding") -> Dict[str, Any]:
+    """
+    End-to-end matching pipeline.
+
+    Args:
+        record1: backend.models.EntityRecord (Pydantic model)
+        record2: backend.models.EntityRecord (Pydantic model)
+        mode: "embedding" 
+
+    Returns:
+        Dict with keys: overall_decision, reason, field_scores, mode,
+                        processing_time_ms
+    """
+    t0 = time.perf_counter()
+
+    # 1. Flatten nested Pydantic models → flat dicts
+    r1_flat = flatten_entity_record(record1)
+    r2_flat = flatten_entity_record(record2)
+
+    logger.info(
+        "Flattened records — R1 keys: %s | R2 keys: %s",
+        list(r1_flat.keys()), list(r2_flat.keys()),
+    )
+
+    # 2. Standardize
+    r1_processed = standardize_record(r1_flat)
+    r2_processed = standardize_record(r2_flat)
+
+    logger.info("Standardized records — mode=%s", mode)
+
+    
+    # 4. Match
+    field_results = match_structured_records(r1_processed, r2_processed, mode=mode)
+
+    # 5. Evaluate rules
+   
+    overall_decision, reason = evaluate_matching_rules(field_results)
+
+    # 6. Format
+    formatted_scores = format_results(field_results, r1_processed, r2_processed, mode)
+
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+
+    return {
+        "overall_decision":    overall_decision,
+        "reason":              reason,
+        "field_scores":        formatted_scores,
+        "mode":                mode,
+        "processing_time_ms":  round(elapsed_ms, 2),
+    }
+
+

backend/models.py

@@ -0,0 +1,536 @@
+from pydantic import BaseModel, Field, field_validator, model_validator
+from typing import Dict, List, Optional, Any, Union
+from enum import Enum
+
+
+# =========================================================
+# ENUM
+# =========================================================
+class MatchingMode(str, Enum):
+    """Supported matching modes"""
+    EMBEDDING = "embedding"
+    
+
+# =========================================================
+# CONSTANTS
+# =========================================================
+MISSING_PLACEHOLDERS = {"missing value", "missing", "na", "n/a", "null", "none", "-"}
+
+# ---------------------------------------------------------------------------
+# Flat-format key → EntityRecord field name mapping.
+# To support a new flat key in future, just add it here.
+# ---------------------------------------------------------------------------
+_FLAT_KEY_MAP: Dict[str, str] = {
+    # Personal identifiers
+    "GENDER":            "gender",
+    "NAME":              "name",
+    "FIRSTNAME":         "firstname",
+    "MIDDLENAME":        "middlename",
+    "LASTNAME":          "lastname",
+    "SPOUSENAME":        "spousename",
+    "MOTHERNAME":        "mothername",
+    "FATHERNAME":        "fathername",
+    "COMPANYNAME":       "companyname",
+    "PARENTCOMPANYNAME": "parentcompanyname",
+    # ID documents
+    "AADHAR":            "aadhar",
+    "PAN":               "pan",
+    "LICENSEID":         "licenseid",
+    "PASSPORTID":        "passportid",
+    "VOTERID":           "voterid",
+    # DOB
+    "BIRTHDATE":         "dob",
+    "DOB":               "dob",
+    # Contact — collected into lists
+    "PHONE":             "_phone_flat",
+    "EMAIL":             "_email_flat",
+    # Address components — collected into addresses[0]
+    "ADDRESSLINE":       "_addressline_flat",
+    "CITY":              "_city_flat",
+    "STATE":             "_state_flat",
+    "ZIPCODE":           "_zipcode_flat",
+}
+
+_FLAT_ADDRESS_KEYS = {"_addressline_flat", "_city_flat", "_state_flat", "_zipcode_flat"}
+
+
+def _is_placeholder(val: Any) -> bool:
+    """Return True if value is a known missing/placeholder sentinel."""
+    if val is None:
+        return True
+    return str(val).strip().lower() in MISSING_PLACEHOLDERS
+
+
+def _normalize_flat_to_nested(data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Detect whether *data* is in flat format (uppercase keys like ADDRESSLINE,
+    BIRTHDATE …) and, if so, convert it to the nested EntityRecord format.
+
+    If data already looks nested (has 'addresses' / 'phones' / 'emails' keys)
+    it is returned unchanged — this is the fast-path for the nested format
+    that supports multiple addresses/phones/emails.
+    """
+    # Fast-path: already nested
+    if "addresses" in data or "phones" in data or "emails" in data:
+        return data
+
+    # Check if this looks like flat format
+    upper_keys = {k.upper() for k in data}
+    is_flat = bool(upper_keys & set(_FLAT_KEY_MAP.keys()))
+    if not is_flat:
+        return data  # Unrecognized — pass through and let Pydantic handle
+
+    # ---- Convert flat → nested -------------------------------------------
+    nested: Dict[str, Any] = {}
+    address_parts: Dict[str, str] = {}
+    phones: List[str] = []
+    emails: List[str] = []
+
+    for raw_key, raw_val in data.items():
+        target = _FLAT_KEY_MAP.get(raw_key.upper())
+
+        if target is None:
+            # Unknown flat key — pass through (may end up in custom_fields)
+            nested[raw_key] = raw_val
+            continue
+
+        if _is_placeholder(raw_val):
+            continue
+
+        if target == "_phone_flat":
+            phones.append(str(raw_val).strip())
+        elif target == "_email_flat":
+            emails.append(str(raw_val).strip())
+        elif target in _FLAT_ADDRESS_KEYS:
+            addr_key = target.replace("_flat", "").lstrip("_")
+            address_parts[addr_key] = str(raw_val).strip()
+        else:
+            nested[target] = raw_val
+
+    if address_parts:
+        nested["addresses"] = [address_parts]
+    if phones:
+        nested["phones"] = phones
+    if emails:
+        nested["emails"] = emails
+
+    return nested
+
+
+# =========================================================
+# REQUEST MODELS
+# =========================================================
+class AddressRecord(BaseModel):
+    """A single address entry."""
+    addressline: str = Field(default="", description="Street address")
+    city:        str = Field(default="", description="City name")
+    state:       str = Field(default="", description="State name")
+    zipcode:     str = Field(default="", description="6-digit postal code (pincode)")
+
+    @model_validator(mode="before")
+    @classmethod
+    def strip_address_placeholders(cls, values: Any) -> Any:
+        """Replace placeholder strings in address fields with empty string."""
+        if isinstance(values, dict):
+            return {
+                k: ("" if _is_placeholder(v) else v)
+                for k, v in values.items()
+            }
+        return values
+
+    def is_empty(self) -> bool:
+        """Return True when every field is blank — used to filter ghost entries."""
+        return not any([self.addressline, self.city, self.state, self.zipcode])
+
+
+class EntityRecord(BaseModel):
+    """
+    A single entity record with all possible fields.
+    All fields are optional — only provided fields are matched.
+
+    ── Multi-value fields ──────────────────────────────────────────
+    addresses : List[AddressRecord]
+        Send as many addresses as needed.
+        Duplicates and all-blank entries are removed automatically.
+        Matching uses best-of-N across all address combinations
+        (handled by get_dynamic_fields + embedding_match_addresses
+         in matching_service.py — no service changes needed).
+
+    phones : List[str]
+        Send as many phone numbers as needed.
+        Duplicates and placeholder strings are removed automatically.
+        Matching uses compare_phone_any_match (any-match across all phones).
+
+    emails : List[str]
+        Same as phones, uses compare_email_any_match.
+
+    ── Input formats ───────────────────────────────────────────────
+    Accepts BOTH nested format and flat uppercase-key format.
+    Flat keys are transparently converted to nested via handle_flat_format.
+    """
+
+    # ---- Name fields -------------------------------------------------------
+    name:        str = Field(default="", description="Full name")
+    firstname:   str = Field(default="", description="First name")
+    middlename:  str = Field(default="", description="Middle name")
+    lastname:    str = Field(default="", description="Last name")
+
+    # ---- Related person names ----------------------------------------------
+    mothername:  str = Field(default="", description="Mother's name")
+    fathername:  str = Field(default="", description="Father's name")
+    spousename:  str = Field(default="", description="Spouse's name")
+    othername:   str = Field(default="", description="Other/alias name")
+
+    # ---- Personal info -----------------------------------------------------
+    dob:    str = Field(default="", description="Date of birth (various formats accepted)")
+    gender: str = Field(default="", description="Gender (M/F/Male/Female/Other)")
+
+    # ---- Identity documents ------------------------------------------------
+    aadhar:     str = Field(default="", alias="AADHAR", description="Aadhar number (12 digits)")
+    pan:        str = Field(default="", description="PAN number (AAAAA9999A)")
+    licenseid:  str = Field(default="", description="Driving license number")
+    passportid: str = Field(default="", description="Passport number")
+    voterid:    str = Field(default="", description="Voter ID")
+
+    # ---- Addresses — N entries supported -----------------------------------
+    addresses: List[AddressRecord] = Field(
+        default_factory=list,
+        description=(
+            "List of addresses. Send any number — duplicates and blank entries "
+            "are removed. Matching uses best-of-N across all combinations."
+        )
+    )
+
+    # ---- Contact — N entries supported -------------------------------------
+    phones: List[str] = Field(
+        default_factory=list,
+        description=(
+            "List of phone numbers. Send any number — duplicates and placeholders "
+            "are removed. Matching uses any-match (match if any pair matches)."
+        )
+    )
+    emails: List[str] = Field(
+        default_factory=list,
+        description=(
+            "List of email addresses. Send any number — duplicates and placeholders "
+            "are removed. Matching uses any-match."
+        )
+    )
+
+    # ---- Employment --------------------------------------------------------
+    companyname:       str = Field(default="", description="Company/employer name")
+    parentcompanyname: str = Field(default="", description="Parent company name")
+
+    # ---- Custom fields -----------------------------------------------------
+    custom_fields: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Arbitrary key-value pairs for exact matching (e.g. MemberID, AccountNumber)"
+    )
+
+    # ── model_validator: runs BEFORE individual field validators ──────────
+    @model_validator(mode="before")
+    @classmethod
+    def handle_flat_format(cls, values: Any) -> Any:
+        """
+        Transparently convert flat-format records (uppercase keys like
+        ADDRESSLINE, BIRTHDATE, PHONE …) into the nested format.
+        Already-nested data is returned unchanged.
+        """
+        if isinstance(values, dict):
+            return _normalize_flat_to_nested(values)
+        return values
+
+    # ── Scalar field placeholder cleanup ────────────���────────────────────
+    @field_validator(
+        "name", "firstname", "middlename", "lastname",
+        "mothername", "fathername", "spousename", "othername",
+        "dob", "gender", "aadhar", "pan", "licenseid",
+        "passportid", "voterid", "companyname", "parentcompanyname",
+        mode="before"
+    )
+    @classmethod
+    def strip_missing_placeholders(cls, v):
+        """Convert placeholder strings → empty string."""
+        if isinstance(v, str) and v.strip().lower() in MISSING_PLACEHOLDERS:
+            return ""
+        return v
+
+    # ── phones: deduplicate + strip placeholders ─────────────────────────
+    @field_validator("phones", mode="before")
+    @classmethod
+    def clean_phones(cls, v):
+        if not isinstance(v, list):
+            return v
+        seen, result = set(), []
+        for item in v:
+            s = str(item).strip()
+            if s and s.lower() not in MISSING_PLACEHOLDERS and s not in seen:
+                seen.add(s)
+                result.append(s)
+        return result
+
+    # ── emails: deduplicate + strip placeholders ─────────────────────────
+    @field_validator("emails", mode="before")
+    @classmethod
+    def clean_emails(cls, v):
+        if not isinstance(v, list):
+            return v
+        seen, result = set(), []
+        for item in v:
+            s = str(item).strip().lower()
+            if s and s not in MISSING_PLACEHOLDERS and s not in seen:
+                seen.add(s)
+                result.append(s)
+        return result
+
+    # ── addresses: remove empty entries + deduplicate ────────────────────
+    @field_validator("addresses", mode="after")
+    @classmethod
+    def clean_addresses(cls, v: List[AddressRecord]) -> List[AddressRecord]:
+        """
+        Remove all-blank address entries and deduplicate by
+        (addressline, city, state, zipcode) tuple.
+        This prevents ghost entries from inflating match scores.
+        """
+        seen, result = set(), []
+        for addr in v:
+            if addr.is_empty():
+                continue
+            key = (
+                addr.addressline.strip().lower(),
+                addr.city.strip().lower(),
+                addr.state.strip().lower(),
+                addr.zipcode.strip(),
+            )
+            if key not in seen:
+                seen.add(key)
+                result.append(addr)
+        return result
+
+    model_config = {
+        "populate_by_name": True,
+        "alias_generator": str.upper,
+        "json_schema_extra": {
+            "examples": [
+                # ── Nested format: multiple addresses + phones ──
+                {
+                    "name": "RAJESH KUMAR SHARMA",
+                    "firstname": "RAJESH",
+                    "dob": "15-01-1990",
+                    "aadhar": "234567890123",
+                    "addresses": [
+                        {
+                            "addressline": "123 MG Road, Koramangala",
+                            "city": "Bangalore",
+                            "state": "Karnataka",
+                            "zipcode": "560034"
+                        },
+                        {
+                            "addressline": "45 Brigade Road",
+                            "city": "Bangalore",
+                            "state": "Karnataka",
+                            "zipcode": "560025"
+                        }
+                    ],
+                    "phones": ["9876543210", "9123456789"],
+                    "emails": ["rajesh@example.com"]
+                },
+                # ── Flat format (single address/phone/email) ──
+                {
+                    "NAME":        "RAJESH KUMAR SHARMA",
+                    "BIRTHDATE":   "15-01-1990",
+                    "AADHAR":      "234567890123",
+                    "ADDRESSLINE": "123 MG Road, Koramangala",
+                    "CITY":        "Bangalore",
+                    "STATE":       "Karnataka",
+                    "ZIPCODE":     "560034",
+                    "PHONE":       "9876543210",
+                    "EMAIL":       "rajesh@example.com"
+                }
+            ]
+        }
+    }
+
+
+class MatchRequest(BaseModel):
+    """Request body for matching two entity records."""
+    record1: EntityRecord = Field(..., description="First entity record")
+    record2: EntityRecord = Field(..., description="Second entity record")
+    mode: MatchingMode = Field(
+        default=MatchingMode.EMBEDDING,
+        description="Matching mode: 'embedding'"
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                # ── Example 1: Multiple addresses + phones (nested) ──────────────
+                {
+                    "mode": "embedding",
+                    "record1": {
+                        "NAME": "RAJESH KUMAR SHARMA",
+                        "dob": "15-01-1990",
+                        "phones": ["9876543210", "9123456789"],
+                        "emails": ["rajesh@example.com"],
+                        "addresses": [
+                            {
+                                "addressline": "123 MG Road",
+                                "city": "Bangalore",
+                                "state": "Karnataka",
+                                "zipcode": "560034"
+                            },
+                            {
+                                "addressline": "45 Brigade Road",
+                                "city": "Bangalore",
+                                "state": "Karnataka",
+                                "zipcode": "560025"
+                            }
+                        ]
+                    },
+                    "record2": {
+                        "NAME": "RAJESH K SHARMA",
+                        "dob": "15/01/1990",
+                        "phones": ["9876543210"],
+                        "emails": ["rajesh@example.com"],
+                        "addresses": [
+                            {
+                                "addressline": "123 Mahatma Gandhi Rd",
+                                "city": "Bengaluru",
+                                "state": "KA",
+                                "zipcode": "560034"
+                            },
+                            {
+                                "addressline": "45 Brigade Road",
+                                "city": "Bangalore",
+                                "state": "Karnataka",
+                                "zipcode": "560025"
+                            }
+                        ]
+                    }
+                },
+                # ── Example 2: Flat format ───────────────────────────────────────
+                {
+                    "mode": "embedding",
+                    "record1": {
+                        "GENDER":            "missing value",
+                        "NAME":              "RAJESH KUMAR SHARMA",
+                        "FIRSTNAME":         "missing value",
+                        "MIDDLENAME":        "missing value",
+                        "LASTNAME":          "missing value",
+                        "SPOUSENAME":        "missing value",
+                        "MOTHERNAME":        "missing value",
+                        "FATHERNAME":        "missing value",
+                        "COMPANYNAME":       "missing value",
+                        "PARENTCOMPANYNAME": "missing value",
+                        "AADHAR":            "missing value",
+                        "PAN":               "missing value",
+                        "LICENSEID":         "missing value",
+                        "PASSPORTID":        "missing value",
+                        "VOTERID":           "missing value",
+                        "ADDRESSLINE":       "123 MG Road",
+                        "BIRTHDATE":         "15-01-1990",
+                        "PHONE":             "9876543210",
+                        "EMAIL":             "missing value",
+                        "CITY":              "Bangalore",
+                        "STATE":             "Karnataka",
+                        "ZIPCODE":           "560034"
+                    },
+                    "record2": {
+                        "GENDER":            "missing value",
+                        "NAME":              "RAJESH K SHARMA",
+                        "FIRSTNAME":         "missing value",
+                        "MIDDLENAME":        "missing value",
+                        "LASTNAME":          "missing value",
+                        "SPOUSENAME":        "missing value",
+                        "MOTHERNAME":        "missing value",
+                        "FATHERNAME":        "missing value",
+                        "COMPANYNAME":       "missing value",
+                        "PARENTCOMPANYNAME": "missing value",
+                        "AADHAR":            "missing value",
+                        "PAN":               "missing value",
+                        "LICENSEID":         "missing value",
+                        "PASSPORTID":        "missing value",
+                        "VOTERID":           "missing value",
+                        "ADDRESSLINE":       "123 Mahatma Gandhi Rd",
+                        "BIRTHDATE":         "15/01/1990",
+                        "PHONE":             "9876543210",
+                        "EMAIL":             "missing value",
+                        "CITY":              "Bengaluru",
+                        "STATE":             "KA",
+                        "ZIPCODE":           "560034"
+                    }
+                }
+            ]
+        }
+    }
+
+
+class BatchMatchRequest(BaseModel):
+    """Request body for batch matching (load testing)."""
+    pairs: List[MatchRequest] = Field(
+        ...,
+        description="List of record pairs to match",
+        min_length=1,
+        max_length=100
+    )
+
+
+# =========================================================
+# RESPONSE MODELS
+# =========================================================
+class FieldScore(BaseModel):
+    """Individual field matching result."""
+    field: str
+    score: Union[float, str] = Field(
+        description="Numeric score (0-100) in embedding mode"
+    )
+
+
+class MatchResult(BaseModel):
+    """Result of matching two entity records."""
+    overall_decision: str = Field(description="'Match' or 'No Match'")
+    reason:           str = Field(description="Human-readable explanation of the matching decision")
+    field_scores: Dict[str, Union[float, str]] = Field(
+        description="Per-field matching scores. Embedding: numeric 0-100."
+    )
+    mode: str = Field(description="Matching mode used: 'embedding'")
+
+
+class MatchResponse(BaseModel):
+    """API response for a single match request."""
+    success: bool = True
+    result:  Optional[MatchResult] = None
+    error:   Optional[str] = None
+    processing_time_ms: float = Field(description="Time taken to process this match in milliseconds")
+
+    model_config = {"populate_by_name": True}
+
+
+class BatchMatchResponse(BaseModel):
+    """API response for batch matching."""
+    success:  bool = True
+    total:    int  = Field(description="Total number of pairs submitted")
+    completed: int = Field(description="Number of pairs successfully matched")
+    failed:   int  = Field(description="Number of pairs that failed")
+    results:  List[MatchResponse] = Field(description="Individual match results")
+    total_processing_time_ms: float = Field(description="Total processing time in milliseconds")
+
+    model_config = {"populate_by_name": True}
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+    status:     str = Field(description="'healthy' or 'unhealthy'")
+    version:    str = Field(default="8.0", description="API version")
+    components: Dict[str, str] = Field(
+        description="Health status of individual components (csv_data, embedding_models)"
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response."""
+    success: bool = False
+    error:   str
+    detail:  Optional[str] = None

backend/server.py

@@ -0,0 +1,323 @@
+import sys
+import os
+import time
+import logging
+import traceback
+from typing import List
+from contextlib import asynccontextmanager
+from concurrent.futures import ThreadPoolExecutor, as_completed
+import asyncio
+
+# Ensure project root is importable
+_PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+import requests as http_requests
+
+# -- Project imports ----------------------------------------------------------
+
+
+from backend.models import (
+    MatchRequest,
+    MatchResponse,
+    MatchResult,
+    BatchMatchRequest,
+    BatchMatchResponse,
+    HealthResponse,
+    ErrorResponse,
+)
+
+from backend.matching_service import perform_match
+
+# =========================================================
+# LOGGING
+# =========================================================
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(levelname)-7s | %(name)s | %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    force=True,
+    handlers=[logging.StreamHandler(sys.stdout)]
+)
+logger = logging.getLogger("backend_server")
+
+
+# =========================================================
+# LIFESPAN – startup / shutdown hooks
+# =========================================================
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Startup:
+      - Pre-warm embedding models (loaded at import time via model.py)
+      - Check CSV data 
+    Shutdown:
+      - Nothing to close (CSV-based, no database connections)
+    """
+    logger.info("=" * 60)
+    logger.info("Entity Matching backend – Starting up")
+    logger.info("=" * 60)
+
+    logger.info("Embedding models loaded (sentence-transformers).")
+
+    try:
+        from services.config import pin_city_state_df, name_variation_df
+        csv_loaded = not pin_city_state_df.empty
+        logger.info("CSV data source: %s (%d pincode rows)",
+                     "OK" if csv_loaded else "EMPTY",
+                     len(pin_city_state_df))
+    except Exception as e:
+        logger.warning("CSV data source check failed: %s", e)
+
+   
+    logger.info("backend ready to serve requests")
+    logger.info("=" * 60)
+
+    yield  # ── app is running ──
+
+    logger.info("Entity Matching backend – Shutting down")
+
+
+# =========================================================
+# APP INSTANCE
+# =========================================================
+app = FastAPI(
+    title="Entity Matching backend",
+    description=(
+        "Gen AI Record-Level Entity Matching backend.\n\n"
+        "Compares two entity records and determines if they represent the same person/entity.\n\n"
+        "**Multi-value fields:** `addresses`, `phones`, and `emails` each accept a list "
+        "of any length. Matching uses best-of-N for addresses and any-match for phones/emails.\n\n"
+        "**Supported matching modes:**\n"
+        "- `embedding` (default): Sentence Transformers + Fuzzy matching\n"
+        
+        "**Input formats:**\n"
+        "- Nested (recommended for multiple values): pass `addresses`, `phones`, `emails` as lists\n"
+        "- Flat (single address/phone/email): pass uppercase keys like `ADDRESSLINE`, `PHONE`, `EMAIL`"
+    ),
+    version="8.0.0",
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+# -- CORS middleware ----------------------------------------------------------
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # Restrict in production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# =========================================================
+# REQUEST LOGGING MIDDLEWARE
+# =========================================================
+@app.middleware("http")
+async def log_requests(request: Request, call_next):
+    """Log every request with timing."""
+    start = time.perf_counter()
+    response = await call_next(request)
+    elapsed = (time.perf_counter() - start) * 1000
+    logger.info(
+        "%s %s – %d (%.1f ms)",
+        request.method,
+        request.url.path,
+        response.status_code,
+        elapsed,
+    )
+    return response
+
+
+# =========================================================
+# GLOBAL EXCEPTION HANDLER
+# =========================================================
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    logger.error("Unhandled exception: %s\n%s", exc, traceback.format_exc())
+    return JSONResponse(
+        status_code=500,
+        content={
+            "success": False,
+            "error": "Internal server error",
+            "detail": str(exc),
+        },
+    )
+
+
+# =========================================================
+# ENDPOINTS
+# =========================================================
+
+# ── Health Checks ─────────────────────────────────────────────────────────────
+@app.get(
+    "/backend/v1/health",
+    response_model=HealthResponse,
+    tags=["Health"],
+    summary="Full system health check",
+)
+async def health_check():
+    """Check the health of all system components."""
+    components = {}
+
+    try:
+        from services.config import pin_city_state_df
+        components["csv_data"] = (
+            "healthy" if not pin_city_state_df.empty else "unhealthy"
+        )
+    except Exception as e:
+        components["csv_data"] = f"error: {e}"
+
+    try:
+        from services.model import MODEL_STORE
+        components["embedding_models"] = "healthy" if MODEL_STORE else "unhealthy"
+    except Exception as e:
+        components["embedding_models"] = f"error: {e}"
+
+    
+
+    overall = (
+        "healthy"
+        if all(v == "healthy" for v in components.values() if v != "not_configured")
+        else "degraded"
+    )
+    return HealthResponse(status=overall, version="8.0", components=components)
+
+
+
+
+# ── Single Match ──────────────────────────────────────────────────────────────
+@app.post(
+    "/backend/v1/match",
+    response_model=MatchResponse,
+    tags=["Matching"],
+    summary="Match two entity records",
+    responses={
+        200: {"description": "Successful matching result"},
+        400: {"model": ErrorResponse, "description": "Invalid input"},
+        500: {"model": ErrorResponse, "description": "Internal error"},
+    },
+)
+async def match_records(request: MatchRequest):
+    """
+    Compare two entity records and determine if they represent the same entity.
+
+    **Multi-value fields:**
+    Pass `addresses`, `phones`, and `emails` as lists of any length:
+    ```json
+    {
+      "mode": "embedding",
+      "record1": {
+        "NAME": "RAJESH KUMAR SHARMA",
+        "dob": "15-01-1990",
+        "phones": ["9876543210", "9123456789"],
+        "addresses": [
+          {"addressline": "123 MG Road",     "city": "Bangalore", "state": "Karnataka", "zipcode": "560034"},
+          {"addressline": "45 Brigade Road", "city": "Bangalore", "state": "Karnataka", "zipcode": "560025"}
+        ]
+      },
+      "record2": {
+        "NAME": "RAJESH K SHARMA",
+        "dob": "15/01/1990",
+        "phones": ["9876543210"],
+        "addresses": [
+          {"addressline": "123 Mahatma Gandhi Rd", "city": "Bengaluru", "state": "KA", "zipcode": "560034"}
+        ]
+      }
+    }
+    ```
+
+    **Matching strategy for lists:**
+    - `addresses`: best-of-N (highest score across all pair combinations)
+    - `phones`: any-match (match if any phone pair matches)
+    - `emails`: any-match (match if any email pair matches)
+
+    **Modes:**
+    - `embedding` (default): Sentence Transformers + RbackenddFuzz
+    
+    """
+    mode = request.mode.value
+
+    
+    t0 = time.perf_counter()
+    try:
+        # Pre-print to terminal specifically for user visibility
+        import json
+        print("\n\n" + "="*80)
+        print(f" NEW MATCH REQUEST RECEIVED (Mode: {mode})")
+        print("="*80)
+        print(f" RECORD 1 INPUT:\n{json.dumps(request.record1.model_dump(by_alias=True), indent=2)}")
+        print(f" RECORD 2 INPUT:\n{json.dumps(request.record2.model_dump(by_alias=True), indent=2)}")
+        print("-" * 80)
+
+        # perform_match is synchronous (CPU + IO bound); run in thread pool
+        # so it doesn't block the asyncio event loop.
+        result = await asyncio.to_thread(
+            perform_match, request.record1, request.record2, mode=mode
+        )
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        logger.info(
+            "Match complete — decision=%s mode=%s time=%.1fms",
+            result["overall_decision"], mode, elapsed_ms,
+        )
+        
+        # Post-print to terminal specifically for user visibility
+        print("📤 MATCH RESULT OUT:\n" + json.dumps({
+            "overall_decision": result["overall_decision"],
+            "reason": result["reason"],
+            "field_scores": result["field_scores"]
+        }, indent=2))
+        print("="*80 + "\n\n")
+
+        return MatchResponse(
+            success=True,
+            result=MatchResult(
+                overall_decision=result["overall_decision"],
+                reason=result["reason"],
+                field_scores=result["field_scores"],
+                mode=mode,
+            ),
+            processing_time_ms=round(elapsed_ms, 2),
+        )
+    except Exception as e:
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        logger.error("Match failed: %s\n%s", e, traceback.format_exc())
+        return MatchResponse(
+            success=False,
+            error=str(e),
+            processing_time_ms=round(elapsed_ms, 2),
+        )
+
+
+
+# =========================================================
+# ROOT / INFO
+# =========================================================
+@app.get("/", tags=["Info"], include_in_schema=False)
+async def root():
+    return {
+        "service": "Entity Matching backend",
+        "version": "8.0.0",
+        "docs":    "/docs",
+        "health":  "/backend/v1/health",
+    }
+
+
+# =========================================================
+# MAIN (for direct execution: python backend/server.py)
+# =========================================================
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "backend.server:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,
+        log_level="info",
+    )

data/city_prev_pres.csv

@@ -0,0 +1,395 @@
+"variation","standard"
+BENGALURU,BANGALORE
+JULLUNDER,JALANDHAR
+CHERPULASSERY,CHERPULACHERRY
+CHIKKAMAGALUR,CHIKMAGALUR
+CHUCHURA,CHINSURAH MAGRA
+HUBBALLI,HUBLI
+INDUR,INDORE
+KANCHIPURAM,KANCHEEPURAM
+MANDAVGARH,MANDU
+MANGALURU,MANGALORE
+MANSANAGAR,VIJAYAWADA
+NORTH PARAVUR,PARAVUR
+SAS NAGAR,SASNAGAR
+SHAHEED BHAGAT SINGH NAGAR,NAWANSHAHR
+PANAJI,NORTH GOA
+ANDAMAN  NICOBAR ISLANDS,ANDAMANNICOBAR ISLANDS
+ANDAMAN & NICOBAR ISLANDS,ANDAMANNICOBAR ISLANDS
+ARIANKUPPAM COMMUNE PANCHAYAT,ARIANKUPPAMCOMMUNE PANCHAYAT
+BAHOUR COMMUNE PANCHAYAT,BAHOURCOMMUNE PANCHAYAT
+BAKSHI KA TALAB**,BAKSHIKA TALAB
+BAKSHI KA TALAB,BAKSHIKA TALAB
+CHANDRA SEKHARA PURAM,CHANDRASEKHARA PURAM
+CHAUTH KA BARWARA,CHAUTHKA BARWARA
+CHERUKUPALLE H/O ARUMBAKA,CHERUKUPALLEHO ARUMBAKA
+CHERUKUPALLE HO ARUMBAKA,CHERUKUPALLEHO ARUMBAKA
+CHILAKALURIPET H/O.PURUSHOTHA PATNAM,CHILAKALURIPETHOPURUSHOTHA PATNAM
+CHILAKALURIPET HOPURUSHOTHA PATNAM,CHILAKALURIPETHOPURUSHOTHA PATNAM
+CHINSURAH  MAGRA,CHINSURAH MAGRA
+CHINSURAH - MAGRA,CHINSURAH MAGRA
+CHURACHANDPUR NORTH SUB-DIV.,CHURACHANDPURNORTH SUBDIV
+CHURACHANDPUR NORTH SUBDIV,CHURACHANDPURNORTH SUBDIV
+DADRA  NAGAR HAVELI,DADRANAGAR HAVELI
+DADRA & NAGAR HAVELI,DADRANAGAR HAVELI
+DAMAN  DIU,DAMAN DIU
+DAMAN & DIU,DAMAN DIU
+DERA BABA NANAK,DERABABA NANAK
+EAST GARO HILLS,EASTGARO HILLS
+EAST KHASI HILLS,EASTKHASI HILLS
+EGMORE  NUNGAMBAKKAM,EGMORE NUNGAMBAKKAM
+EGMORE - NUNGAMBAKKAM,EGMORE NUNGAMBAKKAM
+FORT  TONDIARPET,FORT TONDIARPET
+FORT - TONDIARPET,FORT TONDIARPET
+GAUTAM BUDDHA NAGAR **,GAUTAMBUDDHA NAGAR
+GAUTAM BUDDHA NAGAR ,GAUTAMBUDDHA NAGAR
+GAUTAM BUDDHA NAGAR,GAUTAMBUDDHA NAGAR
+GOLA GOKARAN NATH,GOLAGOKARAN NATH
+GOOL GULAB GARH,GOOLGULAB GARH
+GUDEM KOTHA VEEDHI,GUDEMKOTHA VEEDHI
+JAJI REDDI GUDEM,JAJIREDDI GUDEM
+JAMMU  KASHMIR,JAMMU KASHMIR
+JAMMU & KASHMIR,JAMMU KASHMIR
+JYOTIBA PHULE NAGAR,JYOTIBAPHULE NAGAR
+KAMJONG CHASSAD SUB-DIV.,KAMJONGCHASSAD SUBDIV
+KAMJONG CHASSAD SUBDIV,KAMJONGCHASSAD SUBDIV
+KEIRAO BITRA SUB-DIVISION,KEIRAOBITRA SUBDIVISION
+KEIRAO BITRA SUBDIVISION,KEIRAOBITRA SUBDIVISION
+KOTTUCHERRY COMMUNE PANCHAYAT,KOTTUCHERRYCOMMUNE PANCHAYAT
+KUSHESHWAR ASTHAN PURBI,KUSHESHWARASTHAN PURBI
+LAHUL  SPITI,LAHUL SPITI
+LAHUL & SPITI,LAHUL SPITI
+MAMBALAM  GUINDY,MAMBALAM GUINDY
+MAMBALAM - GUINDY,MAMBALAM GUINDY
+MANNADIPET COMMUNE PANCHAYAT,MANNADIPETCOMMUNE PANCHAYAT
+MYLAPORE  TRIPLICANE,MYLAPORE TRIPLICANE
+MYLAPORE - TRIPLICANE,MYLAPORE TRIPLICANE
+NEDUNGADU COMMUNE PANCHAYAT,NEDUNGADUCOMMUNE PANCHAYAT
+NEEM CHAK BATHANI,NEEMCHAK BATHANI
+NERAVY COMMUNE PANCHAYAT,NERAVYCOMMUNE PANCHAYAT
+NETTAPAKKAM COMMUNE PANCHAYAT,NETTAPAKKAMCOMMUNE PANCHAYAT
+NORTH 24 PARGANAS,NORTH24 PARGANAS
+NORTH AND MIDDLE ANDAMAN,NORTHANDMIDDLE ANDAMAN
+NORTH CACHAR HILLS,NORTHCACHAR HILLS
+NORTH EAST DELHI,NORTHEAST DELHI
+NORTH WEST DELHI,NORTHWEST DELHI
+PEDDA ADISERLA PALLE,PEDDAADISERLA PALLE
+PERAMBUR  PURASAWAKKAM,PERAMBUR PURASAWAKKAM
+PERAMBUR - PURASAWAKKAM,PERAMBUR PURASAWAKKAM
+POLBA  DADPUR,POLBA DADPUR
+POLBA - DADPUR,POLBA DADPUR
+RAIPUR  KARCHULIYAN,RAIPUR KARCHULIYAN
+RAIPUR - KARCHULIYAN,RAIPUR KARCHULIYAN
+SADAR HILLS EAST SUB-DIVISION,SADARHILLSEAST SUBDIVISION
+SADAR HILLS EAST SUBDIVISION,SADARHILLSEAST SUBDIVISION
+SADAR HILLS WEST SUB-DIVISION,SADARHILLSWEST SUBDIVISION
+SADAR HILLS WEST SUBDIVISION,SADARHILLSWEST SUBDIVISION
+SAITU GAMPHAZOL SUB-DIVISION,SAITUGAMPHAZOL SUBDIVISION
+SAITU GAMPHAZOL SUBDIVISION,SAITUGAMPHAZOL SUBDIVISION
+SANT KABIR NAGAR,SANTKABIR NAGAR
+SANT RAVIDAS NAGAR,SANTRAVIDAS NAGAR
+SAVALYAPURAM H/O KANAMARLAPUDI,SAVALYAPURAMHO KANAMARLAPUDI
+SAVALYAPURAM HO KANAMARLAPUDI,SAVALYAPURAMHO KANAMARLAPUDI
+SOUTH 24 PARGANAS,SOUTH24 PARGANAS
+SOUTH EAST DELHI,SOUTHEAST DELHI
+SOUTH GARO HILLS,SOUTHGARO HILLS
+SOUTH WEST DELHI,SOUTHWEST DELHI
+TAMENGLONG NORTH SUB-DIVISION,TAMENGLONGNORTH SUBDIVISION
+TAMENGLONG NORTH SUBDIVISION,TAMENGLONGNORTH SUBDIVISION
+TELANGANA,ANDHRA PRADESH
+THIRUMALAIRAYAN PATTINAM COMMUNE PANCHAYAT,THIRUMALAIRAYANPATTINAMCOMMUNE PANCHAYAT
+THIRUNALLAR COMMUNE PANCHAYAT,THIRUNALLARCOMMUNE PANCHAYAT
+UDHAM SINGH NAGAR,UDHAMSINGH NAGAR
+UKHRUL CENTRAL SUB-DIVISION,UKHRULCENTRAL SUBDIVISION
+UKHRUL CENTRAL SUBDIVISION,UKHRULCENTRAL SUBDIVISION
+VILLIANUR COMMUNE PANCHAYAT,VILLIANURCOMMUNE PANCHAYAT
+WEST GARO HILLS,WESTGARO HILLS
+WEST KHASI HILLS,WESTKHASI HILLS
+EDLABAD,ADILABAD
+KARNAVATI,AHMEDABAD
+AJAYMERU,AJMER
+ALLEPPEY,ALAPPUZHA
+ALLYGURH,ALIGARH
+PRAYAG,ALLAHABAD
+ALWAYE,ALUVA
+BALLARI,BELLARY
+BURDWAN,BARDHAMAN
+BHIR,BEED
+BELAGAVI,BELGAUM
+BROACH,BHARUCH
+BHAVENA ,BHAVNAGAR
+GOHILWAD,BHAVNAGAR
+BELLASGATE,BHEDAGHAT MARBLES
+VIRAVATI,VADODARA
+CHANDRAVATI,VADODARA
+BARODA,VADODARA
+VADPATRA,VADODARA
+MADRAS,CHENNAI
+CHERPALCHERY,CHERPULACHERRY
+SHERTHALAI,CHERTHALA
+CHIKMAGALUR,CHIKMAGALUR
+CHINSURAH,CHINSURAH MAGRA
+ELLORE,ELURU
+GARTHAPURI,GUNTUR
+GURUGRAM,GURGAON
+GAUHATI,GUWAHATI
+HOSAPETE,HOSPET
+HUBLI,HUBLI
+BHAGYANAGARAM,HYDERABAD
+AHILYANAGARI,INDORE
+JUBBULPORE,JABALPUR
+KADAPA,CUDDAPAH
+COCANADA,KAKINADA
+KALABURAGI,GULBARGA
+CONJEEVARAM,KANCHEEPURAM
+CANNANORE,KANNUR
+CAWNPORE,KANPUR
+CAPE COMORIN,KANYAKUMARI
+ELAGANDLA,KARIMNAGAR
+KARUVUR,KARUR
+CAMBAY,KHAMBHAT
+COCHIN,KOCHI
+CRANGANORE,KODUNGALLUR
+CALCUTTA,KOLKATA
+QUILON,KOLLAM
+KONEY,KONNI
+CALICUT,KOZHIKODE
+KANDENAVOLU,KURNOOL
+MUZAFFARNAGAR,MUZAFFARNAGAR
+LAKSHMINAGAR,MUZAFFARNAGAR
+MASULIPATAM,MACHILIPATNAM
+MARCERA,MADIKERI
+PALAMURU,MAHBUBNAGAR
+MANDU,MANDU
+MANDAV NAGAR,MANDI
+MANGALORE,MANGALORE
+KRISHNA,VIJAYAWADA
+MAYAVARAM,MAYILADUTHURAI
+SIDDAPURAM,MEDAK
+METUKU SEEMA,MEDAK
+BOMBAY,MUMBAI
+MYSORE,MYSURU
+NOWGONG,NAGAON
+NASIK,NASHIK
+VIKRAMA SIMHAPURI,NELLORE
+PARUR,PARAVUR
+EKASILANAGARAM,WARANGAL
+ORUGALLU,WARANGAL
+PALAI,PALA
+PALGHAT,PALAKKAD
+PANJIM,NORTH GOA
+PORTO NOVO,PARANGIPETTAI
+PRAKASAM,ONGOLE
+PUDUCHERRY ,PONDICHERRY
+POONA,PUNE
+RASSEN,RAISEN
+RAJAMAHENDRAVARAMU,RAJAHMUNDRY
+KANPUR DEHAT,KANPUR DEHAT
+RAMABAI NAGAR,KANPUR DEHAT
+ROPAR,RUPNAGAR
+SAUGOR,SAGAR
+MOHALI,SASNAGAR
+VIRATNAGARI,SHAHDOL
+NAWAN SHAHAR,NAWANSHAHR
+SIMLA,SHIMLA
+SHIVAMOGGA,SHIMOGA
+SAIHA,SAIHA
+SIVASAGAR,SIBSAGAR
+SRI POTTI SRI RAMULU NELLORE,NELLORE
+SIKKOLU,SRIKAKULAM
+SURYAPUR,SURAT
+TELLICHERRY,THALASSERY
+THANA,THANE
+TANJORE,THANJAVUR
+TRANQUEBAR,THARANGAMBADI
+TRIVANDRUM,THIRUVANANTHAPURAM
+TUTICORIN,THOOTHUKKUDI
+TRICHUR,THRISSUR
+TRICHINOPOLY,TIRUCHIRAPPALLI
+TINNEVELLY,TIRUNELVELI
+TRINOMALEE,TIRUVANNAMALAI
+TUMAKURU,TUMKUR
+OOTACAMUND,UDHAGAMANDALAM
+AVANTIKA,UJJAIN
+OJJAIN,UJJAIN
+BULSAR,VALSAD
+BANARAS,VARANASI
+BADAGARA,VADAKARA
+BHELSA,VIDISHA
+VIJAYAPURA,BIJAPUR
+BEZAWADA,VIJAYAWADA
+VIRUDUPATTI,VIRUDHUNAGAR
+WALTAIR,VISAKHAPATNAM
+VIZAGAPATAM,VISAKHAPATNAM
+YSR DISTRICT,CUDDAPAH
+MUMBAI,MUMBAI
+BOMBAY,MUMBAI
+MUMBAI SUBURBAN,MUMBAI
+DELHI,DELHI
+NEW DELHI,DELHI
+DELHI NCR,DELHI
+NCT OF DELHI,DELHI
+SEELAMPUR,DELHI
+SHAHDARA,DELHI
+DWARKA,DELHI
+ROHINI,DELHI
+PITAMPURA,DELHI
+KAROL BAGH,DELHI
+LAJPAT NAGAR,DELHI
+SAKET,DELHI
+JANAKPURI,DELHI
+MAYUR VIHAR,DELHI
+VASANT KUNJ,DELHI
+OKHLA,DELHI
+BENGALURU,BENGALURU
+BANGALORE,BENGALURU
+BENGALURU URBAN,BENGALURU
+HYDERABAD,HYDERABAD
+SECUNDERABAD,HYDERABAD
+HYDERABAD CITY,HYDERABAD
+CHENNAI,CHENNAI
+MADRAS,CHENNAI
+CHENNAI CITY,CHENNAI
+KOLKATA,KOLKATA
+CALCUTTA,KOLKATA
+KOLKATA CITY,KOLKATA
+PUNE,PUNE
+POONA,PUNE
+AHMEDABAD,AHMEDABAD
+AMDAVAD,AHMEDABAD
+JAIPUR,JAIPUR
+PINK CITY,JAIPUR
+LUCKNOW,LUCKNOW
+LAKHNAU,LUCKNOW
+KANPUR,KANPUR
+CAWNPORE,KANPUR
+NAGPUR,NAGPUR
+INDORE,INDORE
+THANE,THANE
+THANA,THANE
+BHOPAL,BHOPAL
+VISAKHAPATNAM,VISAKHAPATNAM
+VIZAG,VISAKHAPATNAM
+VISHAKHAPATNAM,VISAKHAPATNAM
+PIMPRI-CHINCHWAD,PIMPRI-CHINCHWAD
+PIMPRI CHINCHWAD,PIMPRI-CHINCHWAD
+PCMC,PIMPRI-CHINCHWAD
+PATNA,PATNA
+PATALIPUTRA,PATNA
+VADODARA,VADODARA
+BARODA,VADODARA
+GHAZIABAD,GHAZIABAD
+GHZ,GHAZIABAD
+LUDHIANA,LUDHIANA
+AGRA,AGRA
+NASHIK,NASHIK
+NASIK,NASHIK
+FARIDABAD,FARIDABAD
+MEERUT,MEERUT
+RAJKOT,RAJKOT
+KALYAN-DOMBIVLI,KALYAN-DOMBIVLI
+KALYAN,KALYAN-DOMBIVLI
+DOMBIVLI,KALYAN-DOMBIVLI
+VASAI-VIRAR,VASAI-VIRAR
+VASAI,VASAI-VIRAR
+VIRAR,VASAI-VIRAR
+VARANASI,VARANASI
+BANARAS,VARANASI
+BENARES,VARANASI
+KASHI,VARANASI
+SRINAGAR,SRINAGAR
+AURANGABAD,AURANGABAD
+DHANBAD,DHANBAD
+AMRITSAR,AMRITSAR
+NAVI MUMBAI,NAVI MUMBAI
+NEW BOMBAY,NAVI MUMBAI
+ALLAHABAD,ALLAHABAD
+PRAYAGRAJ,ALLAHABAD
+ILAHABAD,ALLAHABAD
+RANCHI,RANCHI
+HOWRAH,HOWRAH
+HAORA,HOWRAH
+COIMBATORE,COIMBATORE
+JABALPUR,JABALPUR
+JUBBULPORE,JABALPUR
+GWALIOR,GWALIOR
+VIJAYAWADA,VIJAYAWADA
+JODHPUR,JODHPUR
+MADURAI,MADURAI
+RAIPUR,RAIPUR
+KOTA,KOTA
+GUWAHATI,GUWAHATI
+GAUHATI,GUWAHATI
+CHANDIGARH,CHANDIGARH
+MOHALI,CHANDIGARH
+SAS NAGAR,CHANDIGARH
+KHARAR,CHANDIGARH
+PANCHKULA,CHANDIGARH
+ZIRAKPUR,CHANDIGARH
+SOLAPUR,SOLAPUR
+SHOLAPUR,SOLAPUR
+HUBLI-DHARWAD,HUBLI-DHARWAD
+HUBLI,HUBLI-DHARWAD
+DHARWAD,HUBLI-DHARWAD
+BAREILLY,BAREILLY
+MORADABAD,MORADABAD
+MYSORE,MYSORE
+MYSURU,MYSORE
+GURGAON,GURGAON
+GURUGRAM,GURGAON
+ALIGARH,ALIGARH
+JALANDHAR,JALANDHAR
+TIRUCHIRAPPALLI,TIRUCHIRAPPALLI
+TRICHY,TIRUCHIRAPPALLI
+TRICHINOPOLY,TIRUCHIRAPPALLI
+BHUBANESWAR,BHUBANESWAR
+BHUBANESHWAR,BHUBANESWAR
+SALEM,SALEM
+WARANGAL,WARANGAL
+THIRUVANANTHAPURAM,THIRUVANANTHAPURAM
+TRIVANDRUM,THIRUVANANTHAPURAM
+GUNTUR,GUNTUR
+BHIWANDI,BHIWANDI
+SAHARANPUR,SAHARANPUR
+GORAKHPUR,GORAKHPUR
+BIKANER,BIKANER
+AMRAVATI,AMRAVATI
+NOIDA,NOIDA
+JAMSHEDPUR,JAMSHEDPUR
+TATANAGAR,JAMSHEDPUR
+BHILAI,BHILAI
+BHILAI NAGAR,BHILAI
+CUTTACK,CUTTACK
+FIROZABAD,FIROZABAD
+KOCHI,KOCHI
+COCHIN,KOCHI
+BHAVNAGAR,BHAVNAGAR
+DEHRADUN,DEHRADUN
+DEHRA DUN,DEHRADUN
+DURGAPUR,DURGAPUR
+ASANSOL,ASANSOL
+NANDED,NANDED
+KOLHAPUR,KOLHAPUR
+AJMER,AJMER
+GULBARGA,GULBARGA
+KALABURAGI,GULBARGA
+JAMNAGAR,JAMNAGAR
+UJJAIN,UJJAIN
+LONI,LONI
+SILIGURI,SILIGURI
+JHANSI,JHANSI
+ULHASNAGAR,ULHASNAGAR
+NELLORE,NELLORE
+JAMMU,JAMMU
+SANGALI-MIRAJ-KUPWAD,SANGALI-MIRAJ-KUPWAD
+SANGALI,SANGALI-MIRAJ-KUPWAD
+MIRAJ,SANGALI-MIRAJ-KUPWAD
+KUPWAD,SANGALI-MIRAJ-KUPWAD
+BELGAUM,BELGAUM
+BELAGAVI,BELGAUM
+MANGALORE,MANGALORE
+MANGALURU,MANGALORE
+AMBATTUR,AMBATTUR
+TIRUNELVELI,TIRUNELVELI
+MALEGAON,MALEGAON
+GREATER NOIDA,GREATER NOIDA

data/hno_variation_standard.csv

@@ -0,0 +1,619 @@
+"variation","standard"
+ ADJUCENT , ADJ 
+ ADJACNT , ADJ 
+ ADJNT , ADJ 
+ ADJT , ADJ 
+ ADJN , ADJ 
+ APPART MENTS , APT 
+APARTMENTSNO,APT
+ APPART MENT , APT 
+ APART MENTS, APT 
+ APPARTMENTS , APT 
+ APART MENT , APT 
+ APARTUMENT , APT 
+ APARTMENTS , APT 
+ APPARTMENT , APT 
+ APARTMENT , APT 
+ APPART , APT 
+ APPATS , APT 
+ APTMNT , APT 
+ APARTM , APT 
+ APATT , APT 
+ APATS , APT 
+ APPTS , APT 
+ APPTT , APT 
+ APRTS , APT 
+ APTMS , APT 
+ APAT , APT 
+ APTS , APT 
+ APPT , APT 
+ APRT , APT 
+ APTT , APT 
+ ARKHADHE , ARCADE 
+ ARKHADE , ARCADE 
+ ARKADE , ARCADE 
+ ARKEDE , ARCADE 
+ ARCAD , ARCADE 
+ ARCDE , ARCADE 
+ AREAA , AREA 
+ ARIAA , AREA 
+ AVENUIE , AVENUE 
+ AVANUE , AVENUE 
+ AVNUE , AVENUE 
+ AVEN , AVENUE 
+ BANC , BANK 
+ BNK , BANK 
+ BASTHY , BASTI 
+ BASTY , BASTI 
+ BEHIND , BEHIND 
+ B/D , BEHIND 
+ BEH , BEHIND 
+ BHI , BEHIND 
+BH, BEHIND 
+ BESIDCE , BESIDE 
+ BE SIDE , BESIDE 
+ BESIDES , BESIDE 
+ BESID , BESIDE 
+  BSD , BESIDE 
+ BUILDINGS , BLDG 
+ BUILDING , BLDG 
+ BUILDIN , BLDG 
+ BUILDG , BLDG 
+ BUILDI , BLDG 
+ BUILDL , BLDG 
+BUILD,BLDG
+ BLDGS , BLDG 
+ BULDG , BLDG 
+ BLIG , BLDG 
+ BULD , BLDG 
+ BDG , BLDG 
+ BLD , BLDG 
+ BLG , BLDG 
+ BLC0K NO , BLOCK  
+ BLOK NO , BLOCK 
+ BLCK NO , BLOCK 
+ BLK NO , BLOCK 
+BL NO,BLOCK 
+ B NO , BLOCK 
+ BNO , BLOCK 
+ BAZAAR , BZR 
+ BAZZAR , BZR 
+ COLN , CLNY 
+ COLY , CLNY 
+ CLN , CLNY 
+ CLY , CLNY 
+ COL , CLNY 
+ COMPHLEX , CMPLX 
+ COMPLEX , CMPLX 
+ CMPLEX , CMPLX 
+ COMPLX , CMPLX 
+ CMPL , CMPLX 
+ CPLX , CMPLX 
+ CENTRAAL , CNTR 
+ CENTRAL , CNTR 
+ CENTER , CNTR 
+ CENTRE , CNTR 
+ CENTR , CNTR 
+ CENTL , CNTR 
+ CNTRL , CNTR 
+ CENT , CNTR 
+ CEN , CNTR 
+ CNT , CNTR 
+ COMPOUND , COMPND 
+ CMPOND , COMPND 
+ COMPD , COMPND 
+ COMPO , COMPND 
+ CMPD , COMPND 
+ CO OPERATIVE , COOP 
+ COOPERATIVE , COOP 
+ CO OPERATE , COOP 
+ CO OPERAT , COOP 
+ CO OPP , COOP 
+ CO-OP , COOP 
+ CO OP HOUSING SOCIETY , COOPHOUSOC 
+ CO OP HOUSING SOC , COOPHOUSOC 
+ CO-OP HOUS SOCTY , COOPHOUSOC 
+ COOP HSG SOCBLDG , COOPHOUSOC 
+ CO- OP HOU SOC , COOPHOUSOC  
+ COOP HSG SOCY , COOPHOUSOC 
+ CO OP HSU SOC , COOPHOUSOC 
+ CO O HSG SOC , COOPHOUSOC
+ COOP HO SOC , COOPHOUSOC 
+ CO OP HOUS , COOPHOUSOC 
+ CO OP SOC , COOPHOUSOC 
+ CO-OP HS , COOPHOUSOC 
+ CHS , COOPHOUSOC 
+ CO OPERATE SOCIETY , COOPSOCIETY 
+ CORNER , CORN 
+CROSS,CROSS
+ DISTRICT , DIST 
+ DISTICT , DIST 
+ DISTR , DIST 
+ DOORNUMBER ,DOOR
+  DOOR NO ,DOOR
+DOORNO,DOOR
+ DOR NO ,DOOR
+  DRNO ,DOOR
+  D NO ,DOOR
+ D-NO ,DOOR
+D.NO,DOOR
+ DNO ,DOOR
+  ENCLAVE , ENCL 
+  ENKLAVE , ENCL 
+ ENCLE , ENCL 
+ ENC , ENCL 
+ ESTATES , ESTATE 
+ ESTAT , ESTATE 
+ ESTA , ESTATE 
+ ESTS , ESTATE 
+ ESTT , ESTATE 
+ EST , ESTATE 
+ EXTENCTION , EXTN 
+ EXTENSION , EXTN 
+  EXT N , EXTN 
+ EXTEN , EXTN 
+ EXETN , EXTN 
+ EXNT , EXTN 
+  EXT , EXTN 
+ EX , EXTN 
+  V TH ,FIFTH
+ FIRST ,FIRST
+   I ST ,FIRST
+ FIRS ,FIRST
+ IST  ,FIRST
+ FIRSTFLOOR , FIRSTFLR 
+ FLATNUMBER , FLAT 
+ F NUMBER , FLAT
+FLAT NOS,FLAT
+FLAT NO,FLAT
+ FLATN O , FLAT 
+FLAT-NO,FLAT
+ FT NO , FLAT 
+ F NO , FLAT
+ FLT , FLAT 
+ FNO , FLAT
+FT,FLAT
+ FLOO , FLR 
+ FLOR , FLR 
+ FLUR , FLR 
+ FR , FLR 
+ FL , FLR 
+ IVTH ,FOURTH
+ GALLI , GALLY 
+ GILLY , GALLY 
+ GULLY , GALLY 
+ GALA , GALLY 
+ GALI , GALLY 
+ GADENS , GARDENS 
+  GRDENS , GARDENS 
+  GARDNS , GARDENS 
+  GRDNS , GARDENS 
+  GDNS , GARDENS 
+  GROIUND , GND 
+ GROUND , GND 
+ GRD , GND 
+ GR  , GND 
+ GROUNDFLOOR ,GNDFLR
+ GOVERNMENT , GOVT 
+ GAVERNMENT , GOVT 
+ GOVRNMNT , GOVT 
+ GOV , GOVT 
+ GENERAL POST OFFICE , GPO 
+ GENRAL POST OFICE , GPO 
+ GNRL POST OFF , GPO 
+  GENERAL P O , GPO 
+ GPO , GPO 
+ GUNJ , GUNZ 
+ GANJ , GUNZ 
+ HILS , HILLS 
+ HASPATAL , HOSPITAL 
+ HASPITAL , HOSPITAL 
+ HOSPTL , HOSPITAL 
+ HSPTL , HOSPITAL 
+ HOSPI  , HOSPITAL 
+ HOSP , HOSPITAL 
+  HOUSE NUMBER ,HOUSE
+  HOUSENUMBER ,HOUSE
+  HOUSE NO ,HOUSE
+  HAUSE NO ,HOUSE
+  HOUS NO ,HOUSE
+  HOU NO ,HOUSE
+  HUS NO ,HOUSE
+  H-NO ,HOUSE
+  H NO ,HOUSE
+ BAZAR , BZR 
+  BAJAR , BZR 
+ BAZER , BZR 
+ BAZR , BZR 
+ CAMPUS , CAMP 
+ CAMPAS , CAMP 
+ CAMPS , CAMP 
+ CMP , CAMP 
+ COLONY , CLNY 
+ COLNI , CLNY 
+ COLOY , CLNY 
+ CONLY , CLNY 
+H.N.,HOUSE
+H.NO,HOUSE
+HONO,HOUSE
+HNO,HOUSE
+ INDUSTRIALESTATE , INDESTATE 
+ INDUSTREALS , INDL 
+ INDUSTRIAL , INDL 
+ INDUSTRIES , INDL 
+ INDUSTREAL , INDL 
+ INDUSTRY , INDL 
+ INDUST , INDL 
+ INDUL , INDL 
+ INDLL , INDL 
+ INDUS , INDL 
+ INDLS , INDL 
+ INDU , INDL 
+ INDS , INDL 
+ IND , INDL 
+ SECOND ,SECOND
+  II ND ,SECOND
+ IIND ,SECOND
+  2NDFLR  ,SECONDFLOOR 
+ SECTOR , SECT 
+ SECTAR , SECT 
+ SCTR , SECT 
+ SEC , SECT 
+SHOP NO,SHOP
+SHOPNO,SHOP
+SITENO,SITE
+ LMTED , LTD 
+ LT , LTD 
+MAIN,MAIN
+ MRG , MARG 
+ MARKETS , MKT 
+ MARKET , MKT 
+ MRKET , MKT 
+ MEKT , MKT 
+ MRKT , MKT 
+ MKTE , MKT 
+ NAGAR , NGR 
+ NAGER , NGR 
+ NAGR , NGR 
+ NGAR , NGR 
+ NAR , NGR 
+ NG , NGR 
+ NATIONAL HIGH WAY , NH 
+ NATIONAL HI WAY , NH 
+ NATIONAL HYWAY , NH 
+ NHW , NH 
+  NH , NH 
+ NIWAS , NIVAS 
+  NUMBER , NO 
+  NEMBER , NO 
+  NUMBUR , NO 
+  NEMBUR , NO 
+  NUMBR , NO 
+  NMBR , NO 
+ OFFICE , OFF 
+ OFFIC , OFF 
+ OFICE , OFF 
+ O/O , OFF 
+ OPPOSITE , OPP 
+ OPPOSTE , OPP 
+OPPSITE,OPP
+ OPPE , OPP 
+ OPPS , OPP 
+ OPPT , OPP 
+ PHESE , PHASE 
+ FASE , PHASE 
+PHAS,PHASE
+PH,PHASE
+PCKET,PKT
+PKT,PKT
+PLOT SR NO,PLOT
+ PL NUMBER , PLOT  
+  P NUMBER , PLOT 
+PLOT.NO.,PLOT 
+PLOT NO,PLOT 
+PLOT.NO,PLOT
+ PLOT-NO , PLOT 
+PLO NO,PLOT
+ PLOTNO , PLOT 
+ PLT NO , PLOT  
+PL.NO.,PLOT 
+ PL NO , PLOT 
+PLOT,PLOT
+PTNO,PLOT
+ P NO , PLOT 
+PLT,PLOT
+ PNO , PLOT 
+ POST OFFICE , PO 
+ POSTOFFICE , PO 
+ POST OFF , PO 
+ P OFFI , PO 
+ POS OF , PO 
+  POST , PO 
+ P OF , PO 
+ PT , PO 
+ POST BOX , POBOX 
+  PST  BOX , POBOX 
+  P O BOX , POBOX 
+ POST BX , POBOX 
+  POS BOX , POBOX 
+ POCKET ,POCKET 
+ QUARTER NUMBER ,QUTR
+ QUARTERNUMBER ,QUTR
+ QUARTER NO ,QUTR
+ QUARTERS ,QUTR
+QUARTER,QUTR
+ QRTR NO ,QUTR
+ QURT NO ,QUTR
+ QRTERS ,QUTR
+QTR NO,QUTR
+QRT NO,QUTR
+ QR NO ,QUTR
+ QTARS ,QUTR
+ QURTS ,QUTR
+Q. NO,QUTR
+QTRNO,QUTR
+ ADJACENT , ADJ 
+SITE,SITE
+  VI TH ,SIXTH
+ SOCIETY , SOC 
+ SOCTY , SOC 
+ SOSTY , SOC 
+ SOCT , SOC 
+ SCTY , SOC 
+ SOCI , SOC 
+ SOCY , SOC 
+STAGE,STAGE
+ STETION , STN 
+ STATION , STN 
+ STANT , STN 
+ STION , STN 
+ STETION ROAD , STNRD 
+ STATION ROAD , STNRD 
+ SN ROAD , STNRD 
+  STREETNUMBER , STR 
+  ST NUMBER , STR 
+  STREET NO , STR 
+ STREEET , STR 
+ STREET , STR 
+ STREAT , STR 
+ STRAET , STR 
+ STRIT , STR 
+ STRET , STR 
+ STEET , STR 
+  ST NO , STR 
+  STRT , STR 
+ STR, STR 
+ SRT , STR 
+ SU DIVISION , SUBDIVISION 
+ SU DIVIZAN , SUBDIVISION 
+ SU DIVIZON , SUBDIVISION 
+ SUB DIVI , SUBDIVISION 
+ SU DIVIS , SUBDIVISION 
+ SU DVSN , SUBDIVISION 
+SURVEY NO,SURVEY
+SURVEYNO,SURVEY
+SY NO,SURVEY
+ TALUKHAA , TALUKA 
+ TALOOKHA , TALUKA 
+ TALOOKA , TALUKA 
+ TALUQA , TALUKA 
+ TALUCA , TALUKA 
+ TAL , TALUKA 
+  III RD ,THIRD 
+TOWER,TOWER
+  VIHAAR , VIHAR 
+ VIHR , VIHAR 
+ VILL , VILLAGE
+ VILL. , VILLAGE 
+ VILLGE , VILLAGE
+ VILLA , VILLAGE 
+ VILLG , VILLAGE
+ VIL , VILLAGE 
+ WATER TAN , WATERTANK 
+ WATER TNK , WATERTANK 
+ WATR TAN , WATERTANK 
+ WATER TK , WATERTANK 
+ WATER T , WATERTANK 
+ WTR TAN , WATERTANK 
+ WTR TNK , WATERTANK 
+ W TNK , WATERTANK 
+ VINGS , WING 
+ WINGS , WING 
+ VING , WING 
+ CROSS ROAD , XRD 
+ CROSSROAD , XRD 
+ CROSS RD , XRD 
+ XRD , XRD 
+ JONE , ZONE 
+ JUNCTION , JN 
+ JUNCTN , JN 
+ JNCTN , JN 
+ JNCN , JN 
+ JNC , JN 
+ JNT , JN 
+ LINE , LANE 
+ LNE , LANE 
+ LN , LANE 
+LYT,LAYOUT
+ LIMITED , LTD 
+ LIMITID , LTD 
+ LIMETED , LTD 
+ LIMTED , LTD 
+ LIMTD , LTD 
+ FLOOR  , FLR 
+I FLOOR,"1 ST FLR"
+FIRST FLOOR,"1 ST FLR"
+GROUND FLOOR,"0 TH FLR"
+Q NO,QUTR
+ Q-NO ,QUTR
+ QRTS ,QUTR
+ QRS ,QUTR
+ QRT ,QUTR
+ QTS ,QUTR
+QNO ,QUTR
+ QR ,QUTR
+ RAIL , RAILWAY 
+ RAWY , RAILWAY 
+ RLY , RAILWAY 
+ RAILWAYQUARTERS , RAILWAYQTR 
+ RLY QRTS , RAILWAYQTR 
+ RAILWAY STATION , RAILWAYSTN 
+ RAILWAY STION , RAILWAYSTN 
+ RLY STATION , RAILWAYSTN 
+ RL STN , RAILWAYSTN 
+ RESIDENCE , RES 
+ RECIDANCE , RES 
+ RSDENCE , RES 
+ RSDNCE , RES 
+ RESI , RES 
+ RSDN , RES 
+ RS , RES 
+ ROAD NO ,ROAD
+ RAOD NO ,ROAD
+ROADNO,ROAD
+RD NO,ROAD
+ ROADS ,ROAD
+ RHODE ,ROAD
+ ROAD ,ROAD
+ RODE ,ROAD
+ R NO ,ROAD
+ RDNO ,ROAD
+ R-NO ,ROAD
+ RAD ,ROAD
+ ROA ,ROAD
+ ROD ,ROAD
+ROOM NO,ROOM
+ROOMNO,ROOM
+R.NO,ROOM
+R NO,ROOM
+ ROUTE , RT 
+ ROOTE , RT 
+ RUTE , RT 
+ RTE , RT 
+ RUT , RT 
+ S CRUZ , SANTCRUZ 
+ SECCOND ,SECOND
+DISTRICT,DIST
+DIST,DIST
+DST,DIST
+DSTR,DIST
+DT,DIST
+ZILLA,DIST
+JILLA,DIST
+ZILA,DIST
+TALUK,TALUK
+TAL,TALUK
+TALUKA,TALUK
+TQ,TALUK
+TEH,TALUK
+TEHS,TALUK
+TEHSIL,TALUK
+MANDAL,TALUK
+MD,TALUK
+VILLAGE,VILLAGE
+VILL,VILLAGE
+VIL,VILLAGE
+VLG,VILLAGE
+GRAMA,VILLAGE
+GRAM,VILLAGE
+GAON,VILLAGE
+CITY,CITY
+CTY,CITY
+TOWN,CITY
+TWN,CITY
+NAGAR,CITY
+NAG,CITY
+PURAM,CITY
+PURA,CITY
+STATE,STATE
+ST,STATE
+RAJYA,STATE
+PRADESH,STATE
+D NO,HOUSE
+D.NO,HOUSE
+D-NO,HOUSE
+D/NO,HOUSE
+DNO,HOUSE
+DOOR NO,HOUSE
+DOOR NUMBER,HOUSE
+APARTMENT,APT
+APT,APT
+APT NO,APT
+APT NUMBER,APT
+APARTMENT NO,APT
+TOWER,APT
+TOWER NO,APT
+WING,APT
+PHASE,APT
+PHASE NO,APT
+RESIDENCY,APT
+RESIDENTIAL COMPLEX,APT
+HEIGHTS,APT
+ENCLAVE,APT
+APARTMENTS,APT
+SOCIETY,APT
+SOCIETY NO,APT
+CHS,APT
+BLDG,BLDG
+BLDG NO,BLDG
+BUILDING,BLDG
+BUILDING NO,BLDG
+BLK,BLOCK
+BLOCK,BLOCK
+BLOCK NO,BLOCK
+FLAT,FLAT
+FLAT NO,FLAT
+FLAT NUMBER,FLAT
+FLT,FLAT
+FLT NO,FLAT
+UNIT,FLAT
+UNIT NO,FLAT
+UNIT NUMBER,FLAT
+PORTION,FLAT
+PORTION NO,FLAT
+OFFICE NO,FLAT
+OFFICE NUMBER,FLAT
+SHOP NO,SHOP
+SHOP NUMBER,SHOP
+ROAD,ROAD
+RD,ROAD
+R D,ROAD
+MARG,ROAD
+MRG,ROAD
+PATH,ROAD
+STREET,STR
+ST,STR
+STR,STR
+GALI,STR
+GALLLI,STR
+LANE,STR
+LN,STR
+MARG,STR
+PATH,STR
+CIRCLE,STR
+CIR,STR
+SECTOR,STR
+SEC,STR
+LANE,LANE
+LN,LANE
+BYLANE,LANE
+CROSS,LANE
+CR,LANE
+EXTENSION,EXTN
+EXT,EXTN
+EXTN,EXTN
+LOCALITY,LOCALITY
+LAYOUT,LOCALITY
+LYT,LOCALITY
+PHASE,LOCALITY
+PH,LOCALITY
+SECTOR,LOCALITY
+SEC,LOCALITY
+COLONY,CLNY
+COL,CLNY
+CLNY,CLNY
+BUILDING,BUILDING
+APT,BUILDING
+APARTMENT,BUILDING
+BLDG,BUILDING
+TOWER,BUILDING

data/state_name_standard.csv

@@ -0,0 +1,244 @@
+"variation","standard"
+ANDHRA PRADESH,ANDHRA PRADESH
+ANDHRAPRADESH,ANDHRA PRADESH
+ANDHRA,ANDHRA PRADESH
+AP,ANDHRA PRADESH
+A.P,ANDHRA PRADESH
+A.P.,ANDHRA PRADESH
+AP STATE,ANDHRA PRADESH
+IN-AP,ANDHRA PRADESH
+ARUNACHAL PRADESH,ARUNACHAL PRADESH
+ARUNACHAL,ARUNACHAL PRADESH
+AR,ARUNACHAL PRADESH
+A.R,ARUNACHAL PRADESH
+ARUNACHAL PRADESH STATE,ARUNACHAL PRADESH
+IN-AR,ARUNACHAL PRADESH
+ASSAM,ASSAM
+AS,ASSAM
+A.S,ASSAM
+ASSAM STATE,ASSAM
+IN-AS,ASSAM
+BIHAR,BIHAR
+BR,BIHAR
+B.R,BIHAR
+BIHAR STATE,BIHAR
+IN-BR,BIHAR
+CHHATTISGARH,CHHATTISGARH
+CHATTISGARH,CHHATTISGARH
+CHHATISGARH,CHHATTISGARH
+CG,CHHATTISGARH
+C.G,CHHATTISGARH
+CT,CHHATTISGARH
+CHATTISGARH STATE,CHHATTISGARH
+IN-CG,CHHATTISGARH
+GOA,GOA
+GA,GOA
+G.A,GOA
+IN-GA,GOA
+GUJARAT,GUJARAT
+GUJRAT,GUJARAT
+GUJARATH,GUJARAT
+GJ,GUJARAT
+G.J,GUJARAT
+IN-GJ,GUJARAT
+HARYANA,HARYANA
+HARIYANA,HARYANA
+HR,HARYANA
+H.R,HARYANA
+IN-HR,HARYANA
+HIMACHAL PRADESH,HIMACHAL PRADESH
+HIMACHAL,HIMACHAL PRADESH
+HP,HIMACHAL PRADESH
+H.P,HIMACHAL PRADESH
+H.P.,HIMACHAL PRADESH
+IN-HP,HIMACHAL PRADESH
+JHARKHAND,JHARKHAND
+JH,JHARKHAND
+J.H,JHARKHAND
+IN-JH,JHARKHAND
+KARNATAKA,KARNATAKA
+KARNATAK,KARNATAKA
+KARN,KARNATAKA
+KA,KARNATAKA
+K.A,KARNATAKA
+MYSORE STATE,KARNATAKA
+IN-KA,KARNATAKA
+KERALA,KERALA
+KERALAM,KERALA
+KL,KERALA
+K.L,KERALA
+IN-KL,KERALA
+MADHYA PRADESH,MADHYA PRADESH
+MADHYAPRADESH,MADHYA PRADESH
+MADHYA,MADHYA PRADESH
+MP,MADHYA PRADESH
+M.P,MADHYA PRADESH
+M.P.,MADHYA PRADESH
+MP STATE,MADHYA PRADESH
+IN-MP,MADHYA PRADESH
+MAHARASHTRA,MAHARASHTRA
+MAHARASTRA,MAHARASHTRA
+MAHA,MAHARASHTRA
+MH,MAHARASHTRA
+M.H,MAHARASHTRA
+MAHARASHTRA STATE,MAHARASHTRA
+IN-MH,MAHARASHTRA
+MANIPUR,MANIPUR
+MN,MANIPUR
+M.N,MANIPUR
+IN-MN,MANIPUR
+MEGHALAYA,MEGHALAYA
+ML,MEGHALAYA
+M.L,MEGHALAYA
+IN-ML,MEGHALAYA
+MIZORAM,MIZORAM
+MZ,MIZORAM
+M.Z,MIZORAM
+IN-MZ,MIZORAM
+NAGALAND,NAGALAND
+NL,NAGALAND
+N.L,NAGALAND
+IN-NL,NAGALAND
+ODISHA,ODISHA
+ORISSA,ODISHA
+OD,ODISHA
+O.D,ODISHA
+OR,ODISHA
+O.R,ODISHA
+ODISHA STATE,ODISHA
+IN-OD,ODISHA
+PUNJAB,PUNJAB
+PANJAB,PUNJAB
+PB,PUNJAB
+P.B,PUNJAB
+IN-PB,PUNJAB
+RAJASTHAN,RAJASTHAN
+RAJ,RAJASTHAN
+RJ,RAJASTHAN
+R.J,RAJASTHAN
+RAJASTHAN STATE,RAJASTHAN
+IN-RJ,RAJASTHAN
+SIKKIM,SIKKIM
+SK,SIKKIM
+S.K,SIKKIM
+IN-SK,SIKKIM
+TAMIL NADU,TAMIL NADU
+TAMILNADU,TAMIL NADU
+TAMIL,TAMIL NADU
+TN,TAMIL NADU
+T.N,TAMIL NADU
+T.N.,TAMIL NADU
+TAMILNADU STATE,TAMIL NADU
+IN-TN,TAMIL NADU
+TELANGANA,TELANGANA
+TELENGANA,TELANGANA
+TG,TELANGANA
+T.G,TELANGANA
+TS,TELANGANA
+T.S,TELANGANA
+TELANGANA STATE,TELANGANA
+IN-TS,TELANGANA
+TRIPURA,TRIPURA
+TR,TRIPURA
+T.R,TRIPURA
+IN-TR,TRIPURA
+UTTAR PRADESH,UTTAR PRADESH
+UTTARPRADESH,UTTAR PRADESH
+UTTAR,UTTAR PRADESH
+UP,UTTAR PRADESH
+U.P,UTTAR PRADESH
+U.P.,UTTAR PRADESH
+UP STATE,UTTAR PRADESH
+IN-UP,UTTAR PRADESH
+UTTARAKHAND,UTTARAKHAND
+UTTARANCHAL,UTTARAKHAND
+UK,UTTARAKHAND
+U.K,UTTARAKHAND
+UA,UTTARAKHAND
+UTTARAKHAND STATE,UTTARAKHAND
+IN-UK,UTTARAKHAND
+WEST BENGAL,WEST BENGAL
+WESTBENGAL,WEST BENGAL
+WB,WEST BENGAL
+W.B,WEST BENGAL
+W.B.,WEST BENGAL
+WEST BENGAL STATE,WEST BENGAL
+IN-WB,WEST BENGAL
+ANDAMAN AND NICOBAR ISLANDS,ANDAMAN AND NICOBAR ISLANDS
+ANDAMAN NICOBAR,ANDAMAN AND NICOBAR ISLANDS
+ANDAMAN,ANDAMAN AND NICOBAR ISLANDS
+NICOBAR,ANDAMAN AND NICOBAR ISLANDS
+AN,ANDAMAN AND NICOBAR ISLANDS
+A.N,ANDAMAN AND NICOBAR ISLANDS
+A & N ISLANDS,ANDAMAN AND NICOBAR ISLANDS
+IN-AN,ANDAMAN AND NICOBAR ISLANDS
+CHANDIGARH,CHANDIGARH
+CH,CHANDIGARH
+C.H,CHANDIGARH
+IN-CH,CHANDIGARH
+MOHALI,CHANDIGARH
+SAS NAGAR,CHANDIGARH
+KHARAR,CHANDIGARH
+PANCHKULA,CHANDIGARH
+ZIRAKPUR,CHANDIGARH
+DADRA AND NAGAR HAVELI AND DAMAN AND DIU,DADRA AND NAGAR HAVELI AND DAMAN AND DIU
+DADRA NAGAR HAVELI,DADRA AND NAGAR HAVELI AND DAMAN AND DIU
+DAMAN DIU,DADRA AND NAGAR HAVELI AND DAMAN AND DIU
+DN,DADRA AND NAGAR HAVELI AND DAMAN AND DIU
+D.N,DADRA AND NAGAR HAVELI AND DAMAN AND DIU
+DNH,DADRA AND NAGAR HAVELI AND DAMAN AND DIU
+DD,DADRA AND NAGAR HAVELI AND DAMAN AND DIU
+IN-DH,DADRA AND NAGAR HAVELI AND DAMAN AND DIU
+DELHI,DELHI
+NEW DELHI,DELHI
+DL,DELHI
+D.L,DELHI
+NCT OF DELHI,DELHI
+NATIONAL CAPITAL TERRITORY OF DELHI,DELHI
+NORTH EAST DELHI,DELHI
+NORTH WEST DELHI,DELHI
+SOUTH EAST DELHI,DELHI
+SOUTH WEST DELHI,DELHI
+SEELAMPUR,DELHI
+SHAHDARA,DELHI
+DWARKA,DELHI
+ROHINI,DELHI
+PITAMPURA,DELHI
+KAROL BAGH,DELHI
+LAJPAT NAGAR,DELHI
+SAKET,DELHI
+JANAKPURI,DELHI
+MAYUR VIHAR,DELHI
+VASANT KUNJ,DELHI
+OKHLA,DELHI
+NOIDA,DELHI
+GREATER NOIDA,DELHI
+FARIDABAD,DELHI
+GHAZIABAD,DELHI
+GHZ,DELHI
+INDIRAPURAM,DELHI
+GURUGRAM,DELHI
+GURGAON,DELHI
+IN-DL,DELHI
+JAMMU AND KASHMIR,JAMMU AND KASHMIR
+JAMMU,JAMMU AND KASHMIR
+KASHMIR,JAMMU AND KASHMIR
+JK,JAMMU AND KASHMIR
+J.K,JAMMU AND KASHMIR
+J&K,JAMMU AND KASHMIR
+JAMMU & KASHMIR,JAMMU AND KASHMIR
+IN-JK,JAMMU AND KASHMIR
+LADAKH,LADAKH
+LA,LADAKH
+L.A,LADAKH
+IN-LA,LADAKH
+LAKSHADWEEP,LAKSHADWEEP
+LAKSHADWEEP ISLANDS,LAKSHADWEEP
+LD,LAKSHADWEEP
+L.D,LAKSHADWEEP
+IN-LD,LAKSHADWEEP
+PUDUCHERRY,PUDUCHERRY
+PONDICHERRY,PUDUCHERRY
+PY,PUDUCHERRY
+P.Y,PUDUCHERRY
+IN-PY,PUDUCHERRY

data/sur_comm_names.csv

@@ -0,0 +1,182 @@
+"s_no","surname_community_extension"
+1,SINGH
+2,SHARMA
+3,GUPTA
+4,VERMA
+5,AGARWAL
+6,AGGARWAL
+7,BANSAL
+8,GOYAL
+9,MITTAL
+10,SRIVASTAVA
+11,CHAUDHARY
+12,CHOUDHARY
+13,PANDEY
+14,MISHRA
+15,TIWARI
+16,YADAV
+17,PATEL
+18,SHAH
+19,MEHTA
+20,DESAI
+21,JOSHI
+22,KULKARNI
+23,PAWAR
+24,JADHAV
+25,SHINDE
+26,REDDY
+27,RAO
+28,NAIDU
+29,VARMA
+30,GOWDA
+31,SHETTY
+32,SETTY
+33,NAIR
+34,PILLAI
+35,MENON
+36,DAS
+37,DUTTA
+38,ROY
+39,SARKAR
+40,MONDAL
+41,GHOSH
+42,BOSE
+43,SEN
+44,THOMAS
+45,MATHEW
+46,JOSEPH
+47,JOHN
+48,GEORGE
+49,KAUR
+50,KHAN
+51,AHMED
+52,AHMAD
+53,ANSARI
+54,SHAIKH
+55,SHEIKH
+56,SYED
+57,HUSSAIN
+58,QURESHI
+59,SIDDIQUI
+60,FAROOQI
+61,PATHAN
+62,BEG
+63,BAIG
+64,MIRZA
+65,USMANI
+66,RAZA
+67,PATAN
+68,NAQVI
+69,RIZVI
+70,KAZMI
+71,ZAIDI
+72,BUKHARI
+73,CHISHTI
+74,MADANI
+75,NOMANI
+76,FARUQI
+77,HASHMI
+78,AZMI
+79,KAZI
+80,QAZI
+81,MEMON
+82,BOHRA
+83,ATTAR
+84,TAMBOLI
+85,NADAF
+86,PINJARI
+87,BAGWAN
+88,KUMAR
+89,KUMARI
+90,DEVI
+91,LAL
+92,PRASAD
+93,CHANDRA
+94,NATH
+95,RAJ
+96,DEV
+97,BABU
+98,MOHAMMED
+99,MUHAMMAD
+100,MOHAMMAD
+101,MOHAMED
+102,MOHD
+103,MD
+104,MHD
+105,ABDUL
+106,ABD
+107,ALI
+108,HASSAN
+109,PAUL
+110,PAL
+111,TRIPATHI
+112,DWIVEDI
+113,CHATURVEDI
+114,UPADHYAY
+115,BHARDWAJ
+116,BHARGAVA
+117,VASHISHTHA
+118,SHUKLA
+119,DUBEY
+120,DUBE
+121,TYAGI
+122,SAXENA
+123,MATHUR
+124,TANDON
+125,KHANNA
+126,ARORA
+127,MALHOTRA
+128,BATRA
+129,GROVER
+130,BEDI
+131,SODHI
+132,AHUJA
+133,CHAWLA
+134,SANDHU
+135,SIDHU
+136,DHILLON
+137,BRAR
+138,RANDHAWA
+139,GILL
+140,MANN
+141,CHEEMA
+142,CHAHAL
+143,PUNIA
+144,JAIN
+145,DOSHI
+146,DALAL
+147,MODI
+148,PAREKH
+149,ZAVERI
+150,SANGHVI
+151,SOMANI
+152,LODHA
+153,LODH
+154,PATIL
+155,DESHMUKH
+156,GAIKWAD
+157,KADAM
+158,KAMBLE
+159,SALUNKHE
+160,BHOSALE
+161,MORE
+162,PENDSE
+163,KARANDE
+164,ACHARYA
+165,HEGDE
+166,BHAT
+167,BHATT
+168,IYER
+169,IYENGAR
+170,MALIK
+171,REHMAN
+172,RAHMAN
+173,AKHTAR
+174,IQBAL
+175,SALMAN
+176,SULTAN
+177,TARIQ
+178,JAVED
+179,FAIZ
+180,rai
+181,

frontend/app.py

@@ -0,0 +1,673 @@
+import gradio as gr
+import json
+import re
+import os
+import requests
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from backend.matching_service import perform_match
+from backend.models import EntityRecord, MatchMode
+
+# =========================================================
+# CONSTANTS
+# =========================================================
+MAX_FIELDS = 20
+
+# =========================================================
+# CUSTOM CSS - Matching the original Streamlit design
+# =========================================================
+CUSTOM_CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+
+* {
+    font-family: 'Inter', sans-serif;
+    box-sizing: border-box;
+}
+
+body, .gradio-container {
+    background-color: #f0f2f5 !important;
+    color: #333 !important;
+}
+
+/* ── App wrapper ── */
+.gradio-container {
+    max-width: 1400px !important;
+    margin: 0 auto !important;
+    padding: 20px !important;
+}
+
+/* ── Header ── */
+.app-header {
+    text-align: center;
+    margin-bottom: 24px;
+    padding: 24px 0 8px;
+}
+.app-header h1 {
+    color: #5B4E8B;
+    font-size: 26px;
+    font-weight: 700;
+    margin: 0 0 6px;
+}
+.app-header p {
+    color: #666;
+    font-size: 14px;
+    margin: 0;
+}
+
+/* ── Record header ── */
+.record-header {
+    color: #612383;
+    font-size: 22px;
+    font-weight: 700;
+    padding-bottom: 10px;
+    margin-bottom: 18px;
+    border-bottom: 3px solid transparent;
+    border-image: linear-gradient(90deg, #612383, #E9592E, #F5A700) 1;
+}
+
+/* ── Section card ── */
+.section-card {
+    background: white;
+    border-radius: 12px;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.08);
+    margin-bottom: 18px;
+    overflow: hidden;
+}
+.section-header-gradient {
+    background: linear-gradient(90deg, #612383 0%, #E9592E 100%);
+    color: white;
+    padding: 12px 18px;
+    font-size: 13px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+}
+.section-body {
+    padding: 18px;
+}
+
+/* ── Gradio overrides ── */
+.gr-form, .gr-box {
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    padding: 0 !important;
+}
+
+label span {
+    color: #555 !important;
+    font-size: 13px !important;
+    font-weight: 500 !important;
+}
+
+input[type="text"], textarea {
+    background-color: #fafbfc !important;
+    color: #333 !important;
+    border: 1px solid #e1e4e8 !important;
+    border-radius: 8px !important;
+    font-size: 14px !important;
+    transition: border-color 0.2s;
+}
+input[type="text"]:focus, textarea:focus {
+    border-color: #E9592E !important;
+    box-shadow: 0 0 0 3px rgba(233,89,46,0.10) !important;
+    outline: none !important;
+}
+
+/* ── Run Match button ── */
+#run-match-btn {
+    background: linear-gradient(90deg, #612383 0%, #E9592E 100%) !important;
+    color: white !important;
+    border: none !important;
+    border-radius: 10px !important;
+    padding: 16px 32px !important;
+    font-size: 16px !important;
+    font-weight: 600 !important;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    box-shadow: 0 4px 12px rgba(97,35,131,0.25) !important;
+    transition: all 0.3s ease;
+    cursor: pointer;
+    width: 100%;
+}
+#run-match-btn:hover {
+    background: linear-gradient(90deg, #E9592E 0%, #612383 100%) !important;
+    transform: translateY(-2px);
+    box-shadow: 0 6px 16px rgba(233,89,46,0.35) !important;
+}
+
+/* ── Add/Remove inline buttons ── */
+.btn-inline {
+    width: 36px !important;
+    height: 36px !important;
+    min-width: 36px !important;
+    padding: 0 !important;
+    border-radius: 6px !important;
+    font-size: 20px !important;
+    font-weight: 500 !important;
+    background-color: white !important;
+    color: #612383 !important;
+    border: 1px solid #d0d7de !important;
+    cursor: pointer;
+}
+.btn-inline:hover {
+    border-color: #28a745 !important;
+    color: #28a745 !important;
+    background: #f6fef9 !important;
+}
+
+/* ── Add Field gradient button ── */
+.btn-add-field {
+    background: linear-gradient(90deg, #612383 0%, #E9592E 100%) !important;
+    color: white !important;
+    border: none !important;
+    border-radius: 8px !important;
+    padding: 10px 22px !important;
+    font-size: 13px !important;
+    font-weight: 600 !important;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    cursor: pointer;
+    margin-top: 10px;
+    box-shadow: 0 3px 8px rgba(97,35,131,0.2);
+}
+.btn-add-field:hover {
+    background: linear-gradient(90deg, #E9592E 0%, #612383 100%) !important;
+}
+
+/* ── Backend status ── */
+.status-online  { color: #28a745; font-weight: 600; font-size: 14px; }
+.status-offline { color: #dc3545; font-weight: 600; font-size: 14px; }
+
+/* ── Result box ── */
+.result-box {
+    background: white;
+    border-radius: 12px;
+    padding: 24px;
+    margin-top: 24px;
+    box-shadow: 0 4px 16px rgba(0,0,0,0.10);
+    border-top: 4px solid transparent;
+    border-image: linear-gradient(90deg, #612383, #E9592E, #F5A700) 1;
+}
+.result-header {
+    color: #612383;
+    font-size: 17px;
+    font-weight: 600;
+    margin-bottom: 12px;
+}
+
+/* ── Subsection label ── */
+.subsection-label {
+    color: #666;
+    font-size: 13px;
+    font-weight: 600;
+    margin: 14px 0 8px;
+    text-transform: uppercase;
+    letter-spacing: 0.3px;
+}
+
+/* ── Address divider ── */
+.addr-divider {
+    border: none;
+    border-top: 1px solid #e1e4e8;
+    margin: 16px 0;
+}
+
+/* ── Accordion / Group override ── */
+.gr-group {
+    border: none !important;
+    background: transparent !important;
+    padding: 0 !important;
+}
+"""
+
+# =========================================================
+# HELPERS
+# =========================================================
+def preprocess_text(text):
+    if not text:
+        return ""
+    return re.sub(r"\s+", " ", text.strip())
+
+
+def check_backend_health():
+    try:
+        r = requests.get("http://127.0.0.1:8000/backend/v1/health", timeout=3)
+        if r.status_code == 200:
+            return "🟢 Backend Server Reachable"
+    except Exception:
+        pass
+    return "🔴 Backend Terminated"
+
+
+def convert_to_api_payload(record: dict) -> dict:
+    payload = {
+        "name":              record.get("name", ""),
+        "firstname":         record.get("firstname", ""),
+        "middlename":        record.get("middlename", ""),
+        "lastname":          record.get("lastname", ""),
+        "mothername":        record.get("mothername", ""),
+        "fathername":        record.get("fathername", ""),
+        "spousename":        record.get("spousename", ""),
+        "othername":         record.get("othername", ""),
+        "dob":               record.get("dob", ""),
+        "gender":            record.get("gender", ""),
+        "AADHAR":            record.get("AADHAR", ""),
+        "pan":               record.get("pan", ""),
+        "licenseid":         record.get("licenseid", ""),
+        "passportid":        record.get("passportid", ""),
+        "voterid":           record.get("voterid", ""),
+        "companyname":       record.get("companyname", ""),
+        "parentcompanyname": record.get("parentcompanyname", ""),
+        "phones":    [],
+        "emails":    [],
+        "addresses": [],
+        "custom_fields": {},
+    }
+
+    for i in range(MAX_FIELDS):
+        val = record.get(f"phone_{i}", "")
+        if val:
+            payload["phones"].append(str(val))
+
+        val = record.get(f"email_{i}", "")
+        if val:
+            payload["emails"].append(str(val))
+
+        addr_keys = [f"addressline_{i}", f"city_{i}", f"state_{i}", f"zipcode_{i}"]
+        if any(k in record for k in addr_keys):
+            addr = {
+                "addressline": record.get(f"addressline_{i}", ""),
+                "city":        record.get(f"city_{i}", ""),
+                "state":       record.get(f"state_{i}", ""),
+                "zipcode":     record.get(f"zipcode_{i}", ""),
+            }
+            payload["addresses"].append(addr)
+
+    known_keys = set(payload.keys()) - {"phones", "emails", "addresses", "custom_fields"}
+    known_prefixes = ("addressline_", "city_", "state_", "zipcode_", "phone_", "email_")
+
+    for k, v in record.items():
+        k_str = str(k)
+        if k_str in known_keys:
+            continue
+        if any(k_str.startswith(p) for p in known_prefixes):
+            continue
+        if v and str(v).strip():
+            payload["custom_fields"][k_str] = str(v)
+
+    return payload
+
+
+# =========================================================
+# MATCH FUNCTION (called by the Run button)
+# =========================================================
+def run_match(
+    # ── Record 1 personal ──
+    r1_name, r1_firstname, r1_middlename, r1_lastname,
+    r1_mothername, r1_fathername, r1_spousename, r1_othername,
+    r1_dob, r1_gender,
+    # ── Record 1 identifiers ──
+    r1_aadhar, r1_pan, r1_licenseid, r1_passportid, r1_voterid,
+    # ── Record 1 addresses (5 slots) ──
+    r1_addr0_line, r1_addr0_city, r1_addr0_state, r1_addr0_zip,
+    r1_addr1_line, r1_addr1_city, r1_addr1_state, r1_addr1_zip,
+    r1_addr2_line, r1_addr2_city, r1_addr2_state, r1_addr2_zip,
+    r1_addr3_line, r1_addr3_city, r1_addr3_state, r1_addr3_zip,
+    r1_addr4_line, r1_addr4_city, r1_addr4_state, r1_addr4_zip,
+    # ── Record 1 phones (5 slots) ──
+    r1_phone0, r1_phone1, r1_phone2, r1_phone3, r1_phone4,
+    # ── Record 1 emails (5 slots) ──
+    r1_email0, r1_email1, r1_email2, r1_email3, r1_email4,
+    # ── Record 1 employment ──
+    r1_company, r1_parent_company,
+    # ── Record 1 custom fields (5 slots) ──
+    r1_cf0_name, r1_cf0_val,
+    r1_cf1_name, r1_cf1_val,
+    r1_cf2_name, r1_cf2_val,
+    r1_cf3_name, r1_cf3_val,
+    r1_cf4_name, r1_cf4_val,
+
+    # ── Record 2 personal ��─
+    r2_name, r2_firstname, r2_middlename, r2_lastname,
+    r2_mothername, r2_fathername, r2_spousename, r2_othername,
+    r2_dob, r2_gender,
+    # ── Record 2 identifiers ──
+    r2_aadhar, r2_pan, r2_licenseid, r2_passportid, r2_voterid,
+    # ── Record 2 addresses (5 slots) ──
+    r2_addr0_line, r2_addr0_city, r2_addr0_state, r2_addr0_zip,
+    r2_addr1_line, r2_addr1_city, r2_addr1_state, r2_addr1_zip,
+    r2_addr2_line, r2_addr2_city, r2_addr2_state, r2_addr2_zip,
+    r2_addr3_line, r2_addr3_city, r2_addr3_state, r2_addr3_zip,
+    r2_addr4_line, r2_addr4_city, r2_addr4_state, r2_addr4_zip,
+    # ── Record 2 phones (5 slots) ──
+    r2_phone0, r2_phone1, r2_phone2, r2_phone3, r2_phone4,
+    # ── Record 2 emails (5 slots) ──
+    r2_email0, r2_email1, r2_email2, r2_email3, r2_email4,
+    # ── Record 2 employment ──
+    r2_company, r2_parent_company,
+    # ── Record 2 custom fields (5 slots) ──
+    r2_cf0_name, r2_cf0_val,
+    r2_cf1_name, r2_cf1_val,
+    r2_cf2_name, r2_cf2_val,
+    r2_cf3_name, r2_cf3_val,
+    r2_cf4_name, r2_cf4_val,
+):
+    def build_record(
+        name, firstname, middlename, lastname,
+        mothername, fathername, spousename, othername, dob, gender,
+        aadhar, pan, licenseid, passportid, voterid,
+        addr_lines, phones, emails,
+        company, parent_company,
+        custom_fields_pairs,
+    ):
+        rec = {
+            "name": name, "firstname": firstname, "middlename": middlename,
+            "lastname": lastname, "mothername": mothername, "fathername": fathername,
+            "spousename": spousename, "othername": othername, "dob": dob, "gender": gender,
+            "AADHAR": aadhar, "pan": pan, "licenseid": licenseid,
+            "passportid": passportid, "voterid": voterid,
+            "companyname": company, "parentcompanyname": parent_company,
+        }
+        for i, (line, city, state, zipcode) in enumerate(addr_lines):
+            rec[f"addressline_{i}"] = line
+            rec[f"city_{i}"]        = city
+            rec[f"state_{i}"]       = state
+            rec[f"zipcode_{i}"]     = zipcode
+        for i, ph in enumerate(phones):
+            rec[f"phone_{i}"] = ph
+        for i, em in enumerate(emails):
+            rec[f"email_{i}"] = em
+        for cf_name, cf_val in custom_fields_pairs:
+            if cf_name and cf_name.strip():
+                rec[cf_name.strip()] = cf_val
+        return rec
+
+    r1 = build_record(
+        r1_name, r1_firstname, r1_middlename, r1_lastname,
+        r1_mothername, r1_fathername, r1_spousename, r1_othername, r1_dob, r1_gender,
+        r1_aadhar, r1_pan, r1_licenseid, r1_passportid, r1_voterid,
+        [
+            (r1_addr0_line, r1_addr0_city, r1_addr0_state, r1_addr0_zip),
+            (r1_addr1_line, r1_addr1_city, r1_addr1_state, r1_addr1_zip),
+            (r1_addr2_line, r1_addr2_city, r1_addr2_state, r1_addr2_zip),
+            (r1_addr3_line, r1_addr3_city, r1_addr3_state, r1_addr3_zip),
+            (r1_addr4_line, r1_addr4_city, r1_addr4_state, r1_addr4_zip),
+        ],
+        [r1_phone0, r1_phone1, r1_phone2, r1_phone3, r1_phone4],
+        [r1_email0, r1_email1, r1_email2, r1_email3, r1_email4],
+        r1_company, r1_parent_company,
+        [
+            (r1_cf0_name, r1_cf0_val), (r1_cf1_name, r1_cf1_val),
+            (r1_cf2_name, r1_cf2_val), (r1_cf3_name, r1_cf3_val),
+            (r1_cf4_name, r1_cf4_val),
+        ],
+    )
+
+    r2 = build_record(
+        r2_name, r2_firstname, r2_middlename, r2_lastname,
+        r2_mothername, r2_fathername, r2_spousename, r2_othername, r2_dob, r2_gender,
+        r2_aadhar, r2_pan, r2_licenseid, r2_passportid, r2_voterid,
+        [
+            (r2_addr0_line, r2_addr0_city, r2_addr0_state, r2_addr0_zip),
+            (r2_addr1_line, r2_addr1_city, r2_addr1_state, r2_addr1_zip),
+            (r2_addr2_line, r2_addr2_city, r2_addr2_state, r2_addr2_zip),
+            (r2_addr3_line, r2_addr3_city, r2_addr3_state, r2_addr3_zip),
+            (r2_addr4_line, r2_addr4_city, r2_addr4_state, r2_addr4_zip),
+        ],
+        [r2_phone0, r2_phone1, r2_phone2, r2_phone3, r2_phone4],
+        [r2_email0, r2_email1, r2_email2, r2_email3, r2_email4],
+        r2_company, r2_parent_company,
+        [
+            (r2_cf0_name, r2_cf0_val), (r2_cf1_name, r2_cf1_val),
+            (r2_cf2_name, r2_cf2_val), (r2_cf3_name, r2_cf3_val),
+            (r2_cf4_name, r2_cf4_val),
+        ],
+    )
+
+    api_url = "http://127.0.0.1:8000/backend/v1/match"
+    try:
+        r1_payload = convert_to_api_payload(r1)
+        r2_payload = convert_to_api_payload(r2)
+
+        rec1 = EntityRecord(**r1_payload)
+        rec2 = EntityRecord(**r2_payload)
+
+        result_data = perform_match(rec1, rec2, mode="embedding")
+
+        result = {
+            "overall_decision": result_data["overall_decision"],
+            "reason":           result_data["reason"],
+            "field_results":    result_data["field_scores"],
+        }
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        return json.dumps({"error": str(e)}, indent=2)
+
+# =========================================================
+# UI BUILDER HELPERS
+# =========================================================
+def section_card(title: str, icon: str = ""):
+    """Returns an HTML header string for a section card."""
+    return f"""
+    <div class="section-card">
+        <div class="section-header-gradient">{icon}&nbsp;&nbsp;{title}</div>
+        <div class="section-body">
+    """
+
+def personal_fields(prefix):
+    inputs = []
+    with gr.Row():
+        full_name  = gr.Textbox(label="Full Name",     placeholder="Enter full name",   elem_id=f"{prefix}_name")
+        first_name = gr.Textbox(label="First Name",    placeholder="Enter first name",  elem_id=f"{prefix}_firstname")
+    inputs += [full_name, first_name]
+    with gr.Row():
+        middle_name = gr.Textbox(label="Middle Name",  placeholder="Enter middle name", elem_id=f"{prefix}_middlename")
+        last_name   = gr.Textbox(label="Last Name",    placeholder="Enter last name",   elem_id=f"{prefix}_lastname")
+    inputs += [middle_name, last_name]
+    with gr.Row():
+        mother_name = gr.Textbox(label="Mother's Name", placeholder="Enter mother's name", elem_id=f"{prefix}_mothername")
+        father_name = gr.Textbox(label="Father's Name", placeholder="Enter father's name", elem_id=f"{prefix}_fathername")
+    inputs += [mother_name, father_name]
+    with gr.Row():
+        spouse_name = gr.Textbox(label="Spouse's Name", placeholder="Enter spouse's name", elem_id=f"{prefix}_spousename")
+        other_name  = gr.Textbox(label="Other Name",    placeholder="Enter other name",     elem_id=f"{prefix}_othername")
+    inputs += [spouse_name, other_name]
+    with gr.Row():
+        dob    = gr.Textbox(label="Date of Birth", placeholder="YYYY-MM-DD",       elem_id=f"{prefix}_dob")
+        gender = gr.Textbox(label="Gender",        placeholder="Male/Female/Other", elem_id=f"{prefix}_gender")
+    inputs += [dob, gender]
+    return inputs   # [name, firstname, middlename, lastname, mothername, fathername, spousename, othername, dob, gender]
+
+def identifier_fields(prefix):
+    inputs = []
+    with gr.Row():
+        aadhar   = gr.Textbox(label="Aadhar Number",   placeholder="Enter Aadhar number",   elem_id=f"{prefix}_aadhar")
+        pan      = gr.Textbox(label="PAN Number",      placeholder="Enter PAN number",       elem_id=f"{prefix}_pan")
+    inputs += [aadhar, pan]
+    with gr.Row():
+        license_ = gr.Textbox(label="License Number",  placeholder="Enter license number",  elem_id=f"{prefix}_license")
+        passport = gr.Textbox(label="Passport Number", placeholder="Enter passport number", elem_id=f"{prefix}_passport")
+    inputs += [license_, passport]
+    with gr.Row():
+        voter_id = gr.Textbox(label="Voter ID",        placeholder="Enter voter ID",        elem_id=f"{prefix}_voterid")
+        gr.HTML("")   # spacer
+    inputs += [voter_id]
+    return inputs   # [aadhar, pan, licenseid, passportid, voterid]
+
+def address_fields(prefix, slot):
+    """Single address slot (0-indexed)."""
+    with gr.Group():
+        label = "Primary Address" if slot == 0 else f"Address {slot+1}"
+        gr.HTML(f'<div class="subsection-label">{label}</div>')
+        line    = gr.Textbox(label="Street Address", placeholder="Street, Building, Area", elem_id=f"{prefix}_addr{slot}_line")
+        with gr.Row():
+            city    = gr.Textbox(label="City",    placeholder="Enter city",    elem_id=f"{prefix}_addr{slot}_city")
+            state   = gr.Textbox(label="State",   placeholder="Enter state",   elem_id=f"{prefix}_addr{slot}_state")
+        zipcode = gr.Textbox(label="Pincode", placeholder="6-digit postal code", elem_id=f"{prefix}_addr{slot}_zip")
+    return line, city, state, zipcode
+
+def contact_fields(prefix):
+    phone_inputs = []
+    email_inputs = []
+    gr.HTML('<div class="subsection-label">📞 Phone Numbers</div>')
+    for i in range(5):
+        ph = gr.Textbox(label=f"Phone {i+1}", placeholder="Enter phone number", elem_id=f"{prefix}_phone{i}")
+        phone_inputs.append(ph)
+    gr.HTML('<hr class="addr-divider"><div class="subsection-label">✉️ Email Addresses</div>')
+    for i in range(5):
+        em = gr.Textbox(label=f"Email {i+1}", placeholder="Enter email address", elem_id=f"{prefix}_email{i}")
+        email_inputs.append(em)
+    return phone_inputs, email_inputs  # each is list of 5
+
+def employment_fields(prefix):
+    with gr.Row():
+        company        = gr.Textbox(label="Company Name",        placeholder="Enter company name",        elem_id=f"{prefix}_company")
+        parent_company = gr.Textbox(label="Parent Company Name", placeholder="Enter parent company name", elem_id=f"{prefix}_pcompany")
+    return company, parent_company
+
+def custom_field_slots(prefix):
+    """5 name+value custom field pairs."""
+    pairs = []
+    gr.HTML('<div class="subsection-label">Custom Fields (up to 5)</div>')
+    for i in range(5):
+        with gr.Row():
+            cf_name = gr.Textbox(label=f"Field Name {i+1}",  placeholder=f"e.g. MemberID", elem_id=f"{prefix}_cf{i}_name")
+            cf_val  = gr.Textbox(label=f"Field Value {i+1}", placeholder="Value",            elem_id=f"{prefix}_cf{i}_val")
+        pairs.append((cf_name, cf_val))
+    return pairs  # list of 5 (name_widget, val_widget) tuples
+
+
+# =========================================================
+# BUILD THE GRADIO APP
+# =========================================================
+def build_app():
+    with gr.Blocks(css=CUSTOM_CSS, title="GEN AI Record Level Matching") as demo:
+
+        # ── Header ──
+        gr.HTML("""
+        <div class="app-header">
+            <h1>Record Level Matching Using Embedding Models</h1>
+            <p>Enter details for two records below and click "Run Record Match" to see the matching result</p>
+        </div>
+        """)
+
+        # ── Backend status (shown once on load) ──
+        backend_status = gr.HTML(value=check_backend_health, every=30)
+
+        # ── Two-column record layout ──
+        with gr.Row(equal_height=False):
+
+            # ════════════════════════
+            # RECORD 1
+            # ════════════════════════
+            with gr.Column():
+                gr.HTML('<div class="record-header">Record 1</div>')
+
+                # Personal Details
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">👤&nbsp;&nbsp;PERSONAL DETAILS</div><div class="section-body">')
+                r1_personal = personal_fields("r1")
+                gr.HTML('</div></div>')
+
+                # Identifiers / Equalities
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">🪪&nbsp;&nbsp;EQUALITIES</div><div class="section-body">')
+                r1_ids = identifier_fields("r1")
+                # Custom fields live inside Equalities (as in original)
+                r1_custom_pairs = custom_field_slots("r1")
+                gr.HTML('</div></div>')
+
+                # Address Details
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">📍&nbsp;&nbsp;ADDRESS DETAILS</div><div class="section-body">')
+                r1_addr_fields = []
+                for slot in range(5):
+                    line, city, state, zipcode = address_fields("r1", slot)
+                    r1_addr_fields += [line, city, state, zipcode]
+                    if slot < 4:
+                        gr.HTML('<hr class="addr-divider">')
+                gr.HTML('</div></div>')
+
+                # Contact Information
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">📱&nbsp;&nbsp;CONTACT INFORMATION</div><div class="section-body">')
+                r1_phones, r1_emails = contact_fields("r1")
+                gr.HTML('</div></div>')
+
+                # Employment Details
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">💼&nbsp;&nbsp;EMPLOYMENT DETAILS</div><div class="section-body">')
+                r1_company, r1_pcompany = employment_fields("r1")
+                gr.HTML('</div></div>')
+
+            # ════════════════════════
+            # RECORD 2
+            # ════════════════════════
+            with gr.Column():
+                gr.HTML('<div class="record-header">Record 2</div>')
+
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">👤&nbsp;&nbsp;PERSONAL DETAILS</div><div class="section-body">')
+                r2_personal = personal_fields("r2")
+                gr.HTML('</div></div>')
+
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">🪪&nbsp;&nbsp;EQUALITIES</div><div class="section-body">')
+                r2_ids = identifier_fields("r2")
+                r2_custom_pairs = custom_field_slots("r2")
+                gr.HTML('</div></div>')
+
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">📍&nbsp;&nbsp;ADDRESS DETAILS</div><div class="section-body">')
+                r2_addr_fields = []
+                for slot in range(5):
+                    line, city, state, zipcode = address_fields("r2", slot)
+                    r2_addr_fields += [line, city, state, zipcode]
+                    if slot < 4:
+                        gr.HTML('<hr class="addr-divider">')
+                gr.HTML('</div></div>')
+
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">📱&nbsp;&nbsp;CONTACT INFORMATION</div><div class="section-body">')
+                r2_phones, r2_emails = contact_fields("r2")
+                gr.HTML('</div></div>')
+
+                gr.HTML('<div class="section-card"><div class="section-header-gradient">💼&nbsp;&nbsp;EMPLOYMENT DETAILS</div><div class="section-body">')
+                r2_company, r2_pcompany = employment_fields("r2")
+                gr.HTML('</div></div>')
+
+        # ── Run Match Button ──
+        run_btn = gr.Button("🔍  RUN RECORD MATCH", variant="primary", elem_id="run-match-btn")
+
+        # ── Result output ──
+        gr.HTML('<div class="result-box"><div class="result-header">Matching Result (Backend API)</div></div>')
+        result_output = gr.Code(label="Result JSON", language="json", lines=20)
+
+        # ── Wire up the button ──
+        # Collect all inputs in exact order matching run_match() signature
+        all_inputs = (
+            r1_personal                                           # 10: name..gender
+            + r1_ids                                              #  5: aadhar..voterid
+            + r1_addr_fields                                      # 20: 5 addr × 4 fields
+            + r1_phones                                           #  5
+            + r1_emails                                           #  5
+            + [r1_company, r1_pcompany]                           #  2
+            + [w for pair in r1_custom_pairs for w in pair]      # 10: 5 pairs × 2
+            + r2_personal                                         # 10
+            + r2_ids                                              #  5
+            + r2_addr_fields                                      # 20
+            + r2_phones                                           #  5
+            + r2_emails                                           #  5
+            + [r2_company, r2_pcompany]                           #  2
+            + [w for pair in r2_custom_pairs for w in pair]      # 10
+        )
+        # Total = 10+5+20+5+5+2+10 + 10+5+20+5+5+2+10 = 57+57 = 114 inputs
+
+        run_btn.click(
+            fn=run_match,
+            inputs=all_inputs,
+            outputs=result_output,
+        )
+
+    return demo
+
+
+# =========================================================
+# ENTRY POINT
+# =========================================================
+if __name__ == "__main__":
+    app = build_app()
+    app.launch()

note.txt

@@ -0,0 +1,48 @@
+Current Version of this application features:
+
+1. dual mode with embedding and llm mode
+2. data preprocessing retrieving from csv data 
+3. Pincode Logic has been updated 
+
+
+
+Objective:
+This repository contains the implementation of a **GenAI-based Entity Matching** system. It supports a dual‑mode architecture with a Fastapi backend, a Streamlit frontend, and a collection of services for data processing and model interaction.
+
+
+Features:
+
+- **Flexible matching service** implemented in `backend/matching_service.py`.
+- **Modular data models** defined in `backend/models.py`.
+- **Streamlit frontend** for quick experimentation (`frontend/app_streamlit.py`).
+- **Configurable rules and LLM model integration** under `services/`.
+- **Extensive test suite** located in `tests/`.
+- **Configuration files** and property management in `backend/config` and `services/config.py`.
+
+
+Active endpoints :
+
+    POST /backend/v1/match         – Match a single pair of records
+    POST /backend/v1/match/batch   – Match multiple pairs  # multithread implementation 
+    GET  /backend/v1/health        – Full health check (CSV data, models, LLM)
+    GET  /backend/v1/health/llm    – LLM server health check only
+
+
+
+
+To Run the application :
+
+for embedding mode: 
+models will be loaded when we initiate the server
+
+for llm mode:
+we have to paste the llm up url in the common.properties , base-url:
+
+for frontend :
+
+python -m streamlit run frontend/app_streamlit.py
+
+
+for backend:
+
+python -m uvicorn backend.server:app 

requirements.txt

@@ -0,0 +1,20 @@
+numpy
+pandas
+python-dateutil
+pytz   
+regex
+scipy
+Pillow
+gradio>=4.44.0
+
+rapidfuzz==3.9.3
+scikit-learn==1.5.2
+sentence-transformers==2.7.0
+pgeocode==0.5.0
+
+
+openai
+torch --index-url https://download.pytorch.org/whl/cpu
+fastapi
+uvicorn
+requests

services/address_matcher.py

@@ -0,0 +1,722 @@
+"""
+address_matcher.py
+==================
+Enhanced Indian address parser + matcher.
+
+Reuses existing infrastructure from rules.py and model.py:
+  - clean_text, strip_non_alphanumeric, deduplicate_consecutive_tokens  (rules.py)
+  - standardize_city, standardize_state                                  (rules.py)
+  - validate_and_normalize_pincode, pincode_similarity_india             (rules.py)
+  - extract_address_components  (rules.py)  ← house/flat/apt/street
+  - roman_to_number             (rules.py)
+  - normalize_and_deduplicate_address (rules.py)
+  - hno_variation_df, city_prev_pres_df, state_name_standard_df,
+    pin_city_state_df, CITY_MAPPING, STATE_MAPPING                       (config via rules.py)
+  - calculate_semantic_similarity, match_entities                        (model.py)
+  - ADDRESS_MODEL_WEIGHTS                                                 (config)
+
+New additions in this file
+--------------------------
+  1. standardize_address_line()    – token-level hno / city / state variation replacement
+  2. extract_geo_anchors()         – PIN / city / state from a *single* address string
+  3. extract_extended_components() – block, sector, ward, apt-name, locality on top of
+                                     the existing extract_address_components()
+  4. match_address_lines()         – full 3-stage pipeline returning score + breakdown
+"""
+
+from __future__ import annotations
+
+import re
+import math
+import logging
+from typing import Dict, Optional, Tuple
+
+logger = logging.getLogger("address_matcher")
+
+# ── existing imports (your project layout) ───────────────────────────────────
+from services.rules import (
+    clean_text,
+    strip_non_alphanumeric,
+    deduplicate_consecutive_tokens,
+    standardize_city,
+    standardize_state,
+    validate_and_normalize_pincode,
+    pincode_similarity_india,
+    extract_address_components,
+    roman_to_number,
+    normalize_and_deduplicate_address,
+    replace_with_standard,
+    lookup_from_mapping,
+)
+from services.config import (
+    hno_variation_df,
+    city_prev_pres_df,
+    state_name_standard_df,
+    pin_city_state_df,
+    CITY_MAPPING,
+    STATE_MAPPING,
+    ADDRESS_MODEL_WEIGHTS,
+)
+from services.model import (
+    calculate_semantic_similarity,
+    match_entities,
+    preprocess_for_matching,
+)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 1. CONSTANTS
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Scoring constants (requirement spec)
+GEO_MISMATCH_SCORE   = 20    # hard cap when city/state/PIN mismatch detected
+GEO_MATCH_BOOST      = 10    # per matching geo component
+ID_MATCH_BOOST       = 30    # numeric identifier components match (gated by embed > 40)
+ID_MISMATCH_PENALTY  = 30    # numeric identifier mismatch penalty
+EMBED_GATE_THRESHOLD = 40    # embedding score must exceed this to award ID_MATCH_BOOST
+
+# Semantic model to use for address residual comparison
+ADDRESS_EMBED_MODEL  = "model2"   # change to "model1" if preferred
+
+# ── Extended component regex patterns ────────────────────────────────────────
+_BLOCK_RE    = re.compile(
+    r'\b(?:block|blk|bl)\.?\s*(?:no\.?\s*)?([a-z0-9]{1,4})\b', re.I)
+_SECTOR_RE   = re.compile(
+    r'\b(?:sector|sec)\.?\s*(?:no\.?\s*)?(\d{1,3}[a-z]?)\b', re.I)
+_WARD_RE     = re.compile(
+    r'\b(?:ward)\.?\s*(?:no\.?\s*)?(\d{1,3}[a-z]?)\b', re.I)
+_PHASE_RE    = re.compile(
+    r'\b(?:phase|ph)\.?\s*(?:no\.?\s*)?(\d{1,2})\b', re.I)
+_PLOT_RE     = re.compile(
+    r'\b(?:plot|plt)\.?\s*(?:no\.?\s*)?([a-z0-9]{1,6}(?:[/-][a-z0-9]{1,4})?)\b', re.I)
+
+# PIN: 6 digits, first digit 1-9 (valid Indian PIN range)
+_PIN_RE      = re.compile(r'(?<!\d)([1-9]\d{5})(?!\d)')
+
+# City / State boundary markers (help isolate tail of address)
+_TAIL_SEP    = re.compile(r'[-–,]\s*')
+
+# Hard identifier component keys – mismatch on ANY of these → -30 penalty
+HARD_ID_KEYS = ('house_number', 'flat_number', 'block', 'sector', 'ward', 'plot', 'phase')
+
+# Geo-anchor keys – mismatch on ANY of these → score = 20 early exit
+GEO_KEYS     = ('pin', 'city', 'state')
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 2. STEP 1 – ADDRESS STANDARDIZATION
+# ────────────────────────────────────────────────────────��────────────────────
+
+def _build_hno_lookup() -> Dict[str, str]:
+    """
+    Build a token-level lookup from hno_variation_df loaded in config.
+    Cached on first call via function attribute.
+    Expected columns: 'variation', 'standard'
+    """
+    if hasattr(_build_hno_lookup, '_cache'):
+        return _build_hno_lookup._cache
+
+    lookup: Dict[str, str] = {}
+    if hno_variation_df is not None and not hno_variation_df.empty:
+        df = hno_variation_df.copy()
+        df.columns = df.columns.str.lower()
+        for _, row in df.iterrows():
+            var = str(row.get('variation', '')).strip().lower()
+            std = str(row.get('standard', '')).strip().lower()
+            if var and std:
+                lookup[var] = std
+
+    _build_hno_lookup._cache = lookup
+    return lookup
+
+
+def standardize_address_line(address: str) -> str:
+    """
+    Stage 0 – token-level standardization of a raw address string.
+
+    Steps (in order):
+      1. clean_text() – strips HTML, control chars, lowercases
+      2. roman_to_number() – "Sector IV" → "Sector 4"
+      3. Replace h_no variation tokens (h.no / hno / h no / door no / d.no …)
+      4. Standardize city tokens via CITY_MAPPING / city_prev_pres_df
+      5. Standardize state tokens via STATE_MAPPING / state_name_standard_df
+      6. Collapse duplicate consecutive tokens
+      7. Strip trailing punctuation noise
+
+    Returns: cleaned, lower-case address string ready for component extraction.
+    """
+    if not address:
+        return ""
+
+    text = clean_text(str(address))           # step 1
+    text = roman_to_number(text)              # step 2
+
+    # step 3 – hno variation token replacement (word-boundary safe)
+    hno_lookup = _build_hno_lookup()
+    if hno_lookup:
+        tokens = text.split()
+        replaced = []
+        i = 0
+        while i < len(tokens):
+            # try 2-token phrases first (e.g. "h no", "door no")
+            two = (tokens[i] + ' ' + tokens[i + 1]).lower() if i + 1 < len(tokens) else ''
+            if two in hno_lookup:
+                replaced.append(hno_lookup[two])
+                i += 2
+                continue
+            one = tokens[i].lower().rstrip('.')
+            if one in hno_lookup:
+                replaced.append(hno_lookup[one])
+            else:
+                replaced.append(tokens[i])
+            i += 1
+        text = ' '.join(replaced)
+
+    # steps 4+5 – city / state token replacement (applied to whole tokens)
+    words = text.split()
+    for idx, word in enumerate(words):
+        # try 2-word combos for multi-word city/state names
+        if idx + 1 < len(words):
+            two_word = word + ' ' + words[idx + 1]
+            city_std = standardize_city(two_word)
+            if city_std and city_std.lower() != two_word.lower():
+                words[idx]     = city_std
+                words[idx + 1] = ''
+                continue
+            state_std = standardize_state(two_word)
+            if state_std and state_std.lower() != two_word.lower():
+                words[idx]     = state_std
+                words[idx + 1] = ''
+                continue
+        single_city  = standardize_city(word)
+        if single_city and single_city.lower() != word.lower():
+            words[idx] = single_city
+            continue
+        single_state = standardize_state(word)
+        if single_state and single_state.lower() != word.lower():
+            words[idx] = single_state
+
+    text = ' '.join(w for w in words if w)
+
+    # step 6+7 – dedup consecutive, strip stray punctuation
+    text = deduplicate_consecutive_tokens(text)
+    text = re.sub(r'\s+', ' ', text).strip(' ,.-')
+    return text
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 3. STEP 2 – GEO-ANCHOR EXTRACTION  (PIN / city / state)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _pin_from_text(text: str) -> Optional[str]:
+    """Extract and validate first Indian PIN from text."""
+    for m in _PIN_RE.finditer(text):
+        candidate = m.group(1)
+        normalized = validate_and_normalize_pincode(candidate)
+        if normalized:
+            return normalized
+    return None
+
+
+def _city_from_text(text: str) -> Optional[str]:
+    """
+    Token scan for city names.
+    Tries 2-word and 1-word combinations against CITY_MAPPING / city_prev_pres_df.
+    Returns the canonical (standardized) city name or None.
+    """
+    tokens = text.split()
+    for i in range(len(tokens)):
+        # 2-word
+        if i + 1 < len(tokens):
+            candidate = tokens[i] + ' ' + tokens[i + 1]
+            std = standardize_city(candidate)
+            if std and std.lower() != candidate.lower():
+                return std.lower()
+            # also accept direct match if it IS a known city already
+            known = lookup_from_mapping(candidate.upper(), CITY_MAPPING)
+            if known:
+                return known.lower()
+        # 1-word
+        std = standardize_city(tokens[i])
+        if std and std.lower() != tokens[i].lower():
+            return std.lower()
+        known = lookup_from_mapping(tokens[i].upper(), CITY_MAPPING)
+        if known:
+            return known.lower()
+    return None
+
+
+def _state_from_text(text: str) -> Optional[str]:
+    """
+    Token scan for state names.
+    Tries 2-word and 1-word combinations.
+    """
+    tokens = text.split()
+    for i in range(len(tokens)):
+        if i + 1 < len(tokens):
+            candidate = tokens[i] + ' ' + tokens[i + 1]
+            std = standardize_state(candidate)
+            if std and std.lower() != candidate.lower():
+                return std.lower()
+            known = lookup_from_mapping(candidate.upper(), STATE_MAPPING)
+            if known:
+                return known.lower()
+        std = standardize_state(tokens[i])
+        if std and std.lower() != tokens[i].lower():
+            return std.lower()
+        known = lookup_from_mapping(tokens[i].upper(), STATE_MAPPING)
+        if known:
+            return known.lower()
+    return None
+
+
+def _enrich_from_pincode(pin: str) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Use pin_city_state_df first, then pgeocode as fallback,
+    to fill in city and state from a PIN code.
+    Returns (city, state) both lowercase or None.
+    """
+    city, state = None, None
+
+    # ── try local CSV first ────────────────────────────────────────────────
+    if pin_city_state_df is not None and not pin_city_state_df.empty:
+        df = pin_city_state_df.copy()
+        df.columns = df.columns.str.lower()
+        # expected columns: pincode / pin, city, state
+        pin_col = next((c for c in df.columns if 'pin' in c), None)
+        if pin_col:
+            row = df[df[pin_col].astype(str).str.zfill(6) == pin]
+            if not row.empty:
+                city_col  = next((c for c in df.columns if 'city' in c), None)
+                state_col = next((c for c in df.columns if 'state' in c), None)
+                if city_col:
+                    city  = str(row.iloc[0][city_col]).strip().lower()
+                if state_col:
+                    state = str(row.iloc[0][state_col]).strip().lower()
+                if city and state:
+                    return standardize_city(city), standardize_state(state)
+
+    # ── pgeocode fallback ──────────────────────────────────────────────────
+    try:
+        import pgeocode
+        nomi = pgeocode.Nominatim('in')
+        result = nomi.query_postal_code(pin)
+        if result is not None and not result.empty:
+            raw_city  = getattr(result, 'county_name',  None)
+            raw_state = getattr(result, 'state_name',   None)
+            if raw_city is not None:
+                cv = raw_city.values[0] if hasattr(raw_city, 'values') else raw_city
+                if cv and not (isinstance(cv, float) and math.isnan(cv)):
+                    city = standardize_city(str(cv).strip().lower())
+            if raw_state is not None:
+                sv = raw_state.values[0] if hasattr(raw_state, 'values') else raw_state
+                if sv and not (isinstance(sv, float) and math.isnan(sv)):
+                    state = standardize_state(str(sv).strip().lower())
+    except Exception:
+        pass
+
+    return city, state
+
+
+def extract_geo_anchors(standardized_address: str) -> Dict[str, Optional[str]]:
+    """
+    Extract { pin, city, state } from a *standardized* address string.
+
+    Priority order:
+      1. PIN extracted from text → pgeocode/CSV fills city+state if absent
+      2. City / state scanned directly from tokens
+      3. Any remaining None fields stay None (component absent)
+    """
+    text = standardized_address
+
+    pin   = _pin_from_text(text)
+    city  = _city_from_text(text)
+    state = _state_from_text(text)
+
+    # Enrich city/state from PIN if either is still missing
+    if pin and (not city or not state):
+        pin_city, pin_state = _enrich_from_pincode(pin)
+        if not city  and pin_city:
+            city  = pin_city
+        if not state and pin_state:
+            state = pin_state
+
+    return {
+        'pin':   pin,
+        'city':  city,
+        'state': state,
+    }
+
+
+def _remove_geo_tokens(text: str, pin: Optional[str],
+                       city: Optional[str], state: Optional[str]) -> str:
+    """
+    Strip extracted geo tokens from the address string so they don't
+    contaminate the residual that goes to the embedding model.
+    """
+    if pin:
+        text = re.sub(re.escape(pin), ' ', text)
+    if city:
+        text = re.sub(re.escape(city), ' ', text, flags=re.I)
+    if state:
+        text = re.sub(re.escape(state), ' ', text, flags=re.I)
+    return re.sub(r'\s+', ' ', text).strip(' ,.-')
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 4. STEP 3 – EXTENDED COMPONENT EXTRACTION
+#    Wraps existing extract_address_components() and adds block/sector/ward/etc.
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _extract_pattern(pattern: re.Pattern, text: str) -> Optional[str]:
+    """Return first group of first match, or None."""
+    m = pattern.search(text)
+    return m.group(1).strip().upper() if m else None
+
+
+def _remove_pattern_match(pattern: re.Pattern, text: str) -> str:
+    """Remove the entire match (not just group 1) from text."""
+    return re.sub(pattern, ' ', text, count=1, flags=re.I)
+
+
+def extract_extended_components(standardized_address: str,
+                                geo: Dict[str, Optional[str]]) -> Dict:
+    """
+    Full component extraction pipeline.
+
+    Returns a dict with keys:
+        house_number, flat_number, apartment, street,   ← from existing rules.py
+        block, sector, ward, phase, plot,               ← new patterns
+        apartment_name,                                  ← existing (apartment field)
+        residual                                         ← leftover for embedding
+    """
+    # ── Step A: strip geo tokens before passing to rules extractor ────────
+    text = _remove_geo_tokens(
+        standardized_address,
+        geo.get('pin'), geo.get('city'), geo.get('state')
+    )
+
+    # ── Step B: existing extractor (house / flat / apartment / street) ────
+    base = extract_address_components(text)
+
+    house_no   = base.get('house_number')
+    flat_no    = base.get('flat_number')
+    apt_name   = base.get('apartment')        # apartment / building name
+    street     = base.get('street')
+    remaining  = base.get('remaining_address', text)
+
+    # ── Step C: extended patterns on the *remaining* text ─────────────────
+    block  = _extract_pattern(_BLOCK_RE,  remaining)
+    if block:
+        remaining = _remove_pattern_match(_BLOCK_RE, remaining)
+
+    sector = _extract_pattern(_SECTOR_RE, remaining)
+    if sector:
+        remaining = _remove_pattern_match(_SECTOR_RE, remaining)
+
+    ward   = _extract_pattern(_WARD_RE,   remaining)
+    if ward:
+        remaining = _remove_pattern_match(_WARD_RE, remaining)
+
+    phase  = _extract_pattern(_PHASE_RE,  remaining)
+    if phase:
+        remaining = _remove_pattern_match(_PHASE_RE, remaining)
+
+    plot   = _extract_pattern(_PLOT_RE,   remaining)
+    if plot:
+        remaining = _remove_pattern_match(_PLOT_RE, remaining)
+
+    # ── Step D: final cleanup of residual ─────────────────────────────────
+    residual = strip_non_alphanumeric(remaining)
+    residual = normalize_and_deduplicate_address(residual)
+    residual = re.sub(r'\s+', ' ', residual).strip()
+
+    return {
+        'house_number':   house_no,
+        'flat_number':    flat_no,
+        'apartment_name': apt_name,
+        'street':         street,
+        'block':          block,
+        'sector':         sector,
+        'ward':           ward,
+        'phase':          phase,
+        'plot':           plot,
+        'residual':       residual,
+    }
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 5. STAGE 1 – GEO-ANCHOR COMPARISON
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _compare_geo(geo1: Dict, geo2: Dict) -> Tuple[Optional[int], int, Dict]:
+    """
+    Compare geo-anchor components of two parsed addresses.
+
+    Returns:
+        (early_exit_score_or_None, geo_boost, details_dict)
+
+    Rules:
+        • If a component is present in BOTH and they differ → score = 20, exit immediately
+        • If a component is present in BOTH and they match  → geo_boost += 10
+        • If absent in either → skip (no boost, no penalty)
+
+    Special case for PIN: uses pincode_similarity_india() distance logic.
+    Two PINs in the same metro cluster are NOT treated as a hard mismatch
+    (similarity_score >= 60 is acceptable). Only cross-city mismatches exit.
+    """
+    geo_boost = 0
+    details   = {}
+
+    # ── PIN comparison ─────────────────────────────────────────────────────
+    p1, p2 = geo1.get('pin'), geo2.get('pin')
+    if p1 and p2:
+        if p1 == p2:
+            geo_boost += GEO_MATCH_BOOST
+            details['pin'] = f'match ({p1}) +{GEO_MATCH_BOOST}'
+        else:
+            pin_result = pincode_similarity_india(p1, p2)
+            sim = pin_result.get('similarity_score', 0) or 0
+            if sim < 60:
+                details['pin'] = f'MISMATCH ({p1} vs {p2}, sim={sim}) → exit={GEO_MISMATCH_SCORE}'
+                return GEO_MISMATCH_SCORE, 0, details
+            else:
+                # Same metro cluster – partial boost
+                geo_boost += GEO_MATCH_BOOST // 2
+                details['pin'] = f'metro-close ({p1} vs {p2}, sim={sim}) +{GEO_MATCH_BOOST // 2}'
+
+    # ── CITY comparison ────────────────────────────────────────────────────
+    c1, c2 = geo1.get('city'), geo2.get('city')
+    if c1 and c2:
+        if c1.lower() == c2.lower():
+            geo_boost += GEO_MATCH_BOOST
+            details['city'] = f'match ({c1}) +{GEO_MATCH_BOOST}'
+        else:
+            details['city'] = f'MISMATCH ({c1} vs {c2}) → exit={GEO_MISMATCH_SCORE}'
+            return GEO_MISMATCH_SCORE, 0, details
+
+    # ── STATE comparison ───────────────────────────────────────────────────
+    s1, s2 = geo1.get('state'), geo2.get('state')
+    if s1 and s2:
+        if s1.lower() == s2.lower():
+            geo_boost += GEO_MATCH_BOOST
+            details['state'] = f'match ({s1}) +{GEO_MATCH_BOOST}'
+        else:
+            details['state'] = f'MISMATCH ({s1} vs {s2}) → exit={GEO_MISMATCH_SCORE}'
+            return GEO_MISMATCH_SCORE, 0, details
+
+    return None, geo_boost, details
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 6. STAGE 2 – HARD IDENTIFIER COMPONENT COMPARISON
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _normalize_id(value: Optional[str]) -> Optional[str]:
+    """
+    Normalize a hard identifier value for comparison.
+    Strips whitespace, uppercase, removes separators (- / .).
+    '4-B', '4B', '4/B' → '4B'
+    """
+    if not value:
+        return None
+    return re.sub(r'[\s\-/.]', '', str(value).strip().upper())
+
+
+def _compare_identifiers(comp1: Dict, comp2: Dict,
+                         embed_score: float) -> Tuple[int, Dict]:
+    """
+    Compare hard identifier components between two parsed addresses.
+
+    Rules:
+      • Both present AND equal             → +30  (only if embed_score > EMBED_GATE_THRESHOLD)
+      • Both present AND NOT equal         → -30  (always, no gate)
+      • Present in one, absent in other    →   0  (no signal either way)
+
+    Returns: (identifier_delta, details_dict)
+    """
+    id_delta = 0
+    details  = {}
+
+    for key in HARD_ID_KEYS:
+        v1 = _normalize_id(comp1.get(key))
+        v2 = _normalize_id(comp2.get(key))
+
+        if v1 and v2:
+            if v1 == v2:
+                if embed_score > EMBED_GATE_THRESHOLD:
+                    id_delta += ID_MATCH_BOOST
+                    details[key] = f'match ({v1}) +{ID_MATCH_BOOST}'
+                else:
+                    details[key] = f'match ({v1}) but embed={embed_score:.1f} < gate → no boost'
+            else:
+                id_delta -= ID_MISMATCH_PENALTY
+                details[key] = f'MISMATCH ({v1} vs {v2}) -{ID_MISMATCH_PENALTY}'
+        elif v1 or v2:
+            details[key] = f'absent in one ({v1 or "–"} vs {v2 or "–"}) → skip'
+
+    return id_delta, details
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 7. STAGE 3 – EMBEDDING / RESIDUAL COMPARISON
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _compute_embed_score(residual1: str, residual2: str) -> float:
+    """
+    Compare two residual address strings using the semantic embedding model.
+    Returns 0–100 float.
+    Falls back to match_entities (fuzzy+semantic) if residuals are very short.
+    """
+    r1 = preprocess_for_matching(residual1)
+    r2 = preprocess_for_matching(residual2)
+
+    if not r1 or not r2:
+        return 0.0
+
+    # For very short residuals (< 4 chars) pure embedding is unreliable;
+    # use the existing match_entities which blends fuzzy + semantic.
+    if len(r1) < 4 or len(r2) < 4:
+        return float(match_entities(r1, r2, weights=ADDRESS_MODEL_WEIGHTS))
+
+    try:
+        raw = calculate_semantic_similarity(ADDRESS_EMBED_MODEL, r1, r2)
+        return max(0.0, min(100.0, float(raw) * 100))
+    except Exception as e:
+        logger.warning(f"Embedding model error: {e}; falling back to match_entities")
+        return float(match_entities(r1, r2, weights=ADDRESS_MODEL_WEIGHTS))
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 8. MASTER PIPELINE  –  match_address_lines()
+# ─────────────────────────────────────────────────────────────────────────────
+
+def match_address_lines(addr1: str, addr2: str) -> Dict:
+    """
+    Full 3-stage Indian address matching pipeline.
+
+    Stage 0 : Standardize both address strings
+    Stage 1 : Geo-anchor extraction + comparison  (city / state / PIN)
+    Stage 2 : Administrative component extraction + comparison
+              (house / flat / block / sector / ward / phase / plot)
+    Stage 3 : Residual embedding comparison (remaining text after extraction)
+
+    Final score formula:
+        final = clamp(embed_score + geo_boost + id_delta, 0, 100)
+
+    Early exit:
+        If any geo component is present in BOTH and they mismatch →
+        return score = GEO_MISMATCH_SCORE (20) immediately.
+
+    Parameters
+    ----------
+    addr1, addr2 : raw address strings (any case, any format)
+
+    Returns
+    -------
+    dict with keys:
+        score          : float  (0–100)
+        early_exit     : bool
+        embed_score    : float
+        geo_boost      : int
+        id_delta       : int
+        breakdown      : dict  (component-level detail)
+        components_1   : dict  (parsed components for addr1)
+        components_2   : dict  (parsed components for addr2)
+    """
+
+    breakdown: Dict = {}
+
+    # ── Stage 0: Standardize ─────────────────────────────────────────────
+    std1 = standardize_address_line(addr1)
+    std2 = standardize_address_line(addr2)
+    breakdown['standardized'] = {'addr1': std1, 'addr2': std2}
+
+    # ── Stage 1: Geo-anchor extraction + comparison ───────────────────────
+    geo1 = extract_geo_anchors(std1)
+    geo2 = extract_geo_anchors(std2)
+    breakdown['geo_components'] = {'addr1': geo1, 'addr2': geo2}
+
+    early_exit_score, geo_boost, geo_detail = _compare_geo(geo1, geo2)
+    breakdown['geo_comparison'] = geo_detail
+
+    if early_exit_score is not None:
+        return {
+            'score':        float(early_exit_score),
+            'early_exit':   True,
+            'embed_score':  0.0,
+            'geo_boost':    0,
+            'id_delta':     0,
+            'breakdown':    breakdown,
+            'components_1': {},
+            'components_2': {},
+        }
+
+    # ── Stage 2: Extended component extraction ────────────────────────────
+    comp1 = extract_extended_components(std1, geo1)
+    comp2 = extract_extended_components(std2, geo2)
+    breakdown['components'] = {'addr1': comp1, 'addr2': comp2}
+
+    # ── Stage 3: Embedding on residuals (needed BEFORE ID comparison) ─────
+    residual1 = comp1.get('residual', '')
+    residual2 = comp2.get('residual', '')
+    embed_score = _compute_embed_score(residual1, residual2)
+    breakdown['embed'] = {
+        'residual_1':   residual1,
+        'residual_2':   residual2,
+        'embed_score':  round(embed_score, 2),
+    }
+
+    # ── Stage 2 (cont.): Identifier comparison (gated by embed score) ─────
+    id_delta, id_detail = _compare_identifiers(comp1, comp2, embed_score)
+    breakdown['id_comparison'] = id_detail
+
+    # ── Final score composition ───────────────────────────────────────────
+    raw_final = embed_score + geo_boost + id_delta
+    final     = max(0.0, min(100.0, raw_final))
+
+    breakdown['score_composition'] = {
+        'embed_score': round(embed_score, 2),
+        'geo_boost':   geo_boost,
+        'id_delta':    id_delta,
+        'raw':         round(raw_final, 2),
+        'final':       round(final, 2),
+    }
+
+    return {
+        'score':        round(final, 2),
+        'early_exit':   False,
+        'embed_score':  round(embed_score, 2),
+        'geo_boost':    geo_boost,
+        'id_delta':     id_delta,
+        'breakdown':    breakdown,
+        'components_1': comp1,
+        'components_2': comp2,
+    }
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 9.  DROP-IN REPLACEMENT FOR match_addresses_1_to_n()  (model.py)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def match_addresses_enhanced(addresses_r1: list, addresses_r2: list) -> float:
+    """
+    1:N address matching using the full pipeline.
+    Replaces / wraps match_addresses_1_to_n() in model.py.
+
+    Returns the highest score found across all address pair combinations.
+    """
+    valid1 = [a for a in addresses_r1 if a and str(a).strip() not in ('', '-', ' ')]
+    valid2 = [a for a in addresses_r2 if a and str(a).strip() not in ('', '-', ' ')]
+
+    if not valid1 or not valid2:
+        return 0.0
+
+    best = 0.0
+    for a1 in valid1:
+        for a2 in valid2:
+            result = match_address_lines(str(a1), str(a2))
+            score  = result.get('score', 0.0)
+            if score > best:
+                best = score
+
+    return best

services/config.py

@@ -0,0 +1,121 @@
+import configparser
+import os
+import ast
+import pandas as pd
+import logging
+
+logger = logging.getLogger("config")
+
+# Initialize config
+logger = logging.getLogger("config")
+
+config = configparser.ConfigParser()
+
+project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# Try backend/config first, then config/ as fallback
+conf_file_path = os.path.join(project_root, "backend", "config", "common.properties")
+if not os.path.exists(conf_file_path):
+    conf_file_path = os.path.join(project_root, "config", "common.properties")
+
+if not os.path.exists(conf_file_path):
+    raise FileNotFoundError(f"common.properties not found. Searched in backend/config/ and config/ under {project_root}")
+
+config.read(conf_file_path)
+
+logger.info(f"Config loaded from: {conf_file_path}")
+#temporary read 
+# print("CONFIG FILES LOADED:", files)
+# print("SECTIONS FOUND:", config.sections())
+
+# Export any config constants if needed
+APARTMENT_IDENTIFIER = config.get("IDENTIFIERS", "APARTMENT_IDENTIFIER")
+FLAT_NUMBER_IDENTIFIER = config.get("IDENTIFIERS", "FLAT_NUMBER_IDENTIFIER")
+HOUSE_NUMBER_IDENTIFIER = config.get("IDENTIFIERS", "HOUSE_NUMBER_IDENTIFIER")
+STREET_KEYWORD = config.get("IDENTIFIERS", "STREET_KEYWORD")
+FLOOR_NO_KEYWORD=config.get("IDENTIFIERS","FLOOR_KEYWORD")
+SURNAME_IDENTIFIER = ast.literal_eval(config.get("IDENTIFIERS","INDIAN_SURNAMES"))
+
+STATE_MAPPING = ast.literal_eval(config.get("MAPPING_DICT", "STATE_MAPPING"))
+CITY_MAPPING = ast.literal_eval(config.get("MAPPING_DICT", "CITY_MAPPING"))
+ADDRESS_MAPPING = ast.literal_eval(config.get("MAPPING_DICT", "ADDRESS_MAPPING"))
+
+MODEL_WEIGHTS = ast.literal_eval(config.get("MATCHING_LOGIC", "MODEL_WEIGHTS"))
+MATCHING_RULES = ast.literal_eval(config.get("MATCHING_LOGIC", "MATCHING_RULES"))
+
+# Name-specific weights (embedding 0.7 + fuzz 0.2 + phonetic 0.1)
+try:
+    NAME_MODEL_WEIGHTS = ast.literal_eval(config.get("NAME_MATCHING", "NAME_MODEL_WEIGHTS"))
+    NAME_MATCH_ADJUSTMENTS = ast.literal_eval(config.get("NAME_MATCHING", "NAME_MATCH_ADJUSTMENTS"))
+except Exception:
+    NAME_MODEL_WEIGHTS = MODEL_WEIGHTS
+    NAME_MATCH_ADJUSTMENTS = {"surname_penalty": -30, "initial_boost": 30, "subset_boost": 40}
+
+# Address-specific weights (embedding + fuzz, no phonetic)
+try:
+    ADDRESS_MODEL_WEIGHTS = ast.literal_eval(config.get("ADDRESS_MATCHING", "ADDRESS_MODEL_WEIGHTS"))
+    ADDRESS_MATCH_ADJUSTMENTS = ast.literal_eval(config.get("ADDRESS_MATCHING", "ADDRESS_MATCH_ADJUSTMENTS"))
+except Exception:
+    ADDRESS_MODEL_WEIGHTS = MODEL_WEIGHTS
+    ADDRESS_MATCH_ADJUSTMENTS = {"house_match_boost": 30, "house_mismatch_penalty": 70}
+
+try:
+    MODEL_1_NAME = config.get("EMBEDDING_MODELS", "MODEL_1_NAME").strip()
+    MODEL_2_NAME = config.get("EMBEDDING_MODELS", "MODEL_2_NAME").strip()
+except Exception:
+    MODEL_1_NAME = "sentence-transformers/all-mpnet-base-v2"
+    MODEL_2_NAME = "sentence-transformers/all-MiniLM-L6-v2"
+
+# =========================================================
+# CSV DATA LOADING (replacing MySQL)
+# =========================================================
+
+def load_csv_file(csv_path: str, file_name: str) -> pd.DataFrame:
+    """Load CSV file as DataFrame with error handling."""
+    try:
+        # Convert to absolute path relative to project root
+        if not os.path.isabs(csv_path):
+            csv_path = os.path.join(project_root, csv_path)
+        
+        # Normalize path and resolve any ../ or ./ references
+        csv_path = os.path.abspath(csv_path)
+        
+        if os.path.exists(csv_path):
+            df = pd.read_csv(csv_path)
+            logger.info(f"Loaded {file_name}: {len(df)} rows from {csv_path}")
+            return df
+        else:
+            logger.warning(f"CSV file not found: {csv_path}")
+            return pd.DataFrame()
+    except Exception as e:
+        logger.error(f"Failed to load {file_name}: {e}")
+        return pd.DataFrame()
+
+# Load CSV reference tables
+try:
+    name_variation_df = load_csv_file(config.get("csv", "name_variation_standard"), "name_variation_standard")
+    hno_variation_df = load_csv_file(config.get("csv", "hno_variation_standard"), "hno_variation_standard")
+    city_prev_pres_df = load_csv_file(config.get("csv", "city_prev_pres"), "city_prev_pres")
+    state_name_standard_df = load_csv_file(config.get("csv", "state_name_standard"), "state_name_standard")
+    sur_comm_names_df = load_csv_file(config.get("csv", "sur_comm_names"), "sur_comm_names")
+    pin_city_state_df = load_csv_file(config.get("csv", "pin_city_state"), "pin_city_state")
+    
+    logger.info("All CSV files loaded successfully")
+except Exception as e:
+    logger.warning(f"Some CSV files may not have loaded: {e}")
+    name_variation_df = pd.DataFrame()
+    hno_variation_df = pd.DataFrame()
+    city_prev_pres_df = pd.DataFrame()
+    state_name_standard_df = pd.DataFrame()
+    sur_comm_names_df = pd.DataFrame()
+    pin_city_state_df = pd.DataFrame()
+
+# Legacy string exports for backward compatibility
+pin_city_state = "pin_city_state"
+sur_comm_names = "sur_comm_names"
+city_prev_pres = "city_prev_pres"
+state_name_standard = "state_name_standard"
+hno_variation_standard = "hno_variation_standard"
+name_variation_standard = "name_variation_standard"
+
+

services/model.py

@@ -0,0 +1,1509 @@
+from concurrent.futures import ThreadPoolExecutor
+from typing import Dict, List, Optional, Tuple
+import pandas as pd
+from rapidfuzz import fuzz
+from rapidfuzz.distance import JaroWinkler
+from sklearn.metrics.pairwise import cosine_similarity
+from sentence_transformers import SentenceTransformer
+import re
+import itertools
+
+from services.config import (
+    SURNAME_IDENTIFIER, MODEL_WEIGHTS, MODEL_1_NAME, MODEL_2_NAME,
+    NAME_MODEL_WEIGHTS, NAME_MATCH_ADJUSTMENTS,
+    ADDRESS_MODEL_WEIGHTS,
+)
+from services.rules import detect_surnames, compute_initial_letter_boost, is_subset_match
+
+# ---------- Model Store ----------
+MODEL_STORE = {}
+
+def get_model(model_name: str) -> SentenceTransformer:
+    if model_name not in MODEL_STORE:
+        print(f"Loading {model_name} into memory on CPU...")
+        if model_name == "model1":
+            MODEL_STORE["model1"] = SentenceTransformer(MODEL_1_NAME, device="cpu")
+        elif model_name == "model2":
+            MODEL_STORE["model2"] = SentenceTransformer(MODEL_2_NAME, device="cpu")
+    return MODEL_STORE[model_name]
+
+
+# ---------- Text Preprocessing ----------
+def preprocess_for_matching(text: str) -> str:
+    """Standardize text for matching"""
+    if not text or text in ["-", " ", ""]:
+        return ""
+    return text.upper().strip()
+
+# ---------- Core Matching Functions ----------
+# ---------- Indic Soundex (phonetic for Indian names) ----------
+# def indic_soundex_code(name: str) -> str:
+#     """
+#     Generate Indic Soundex code for a name token.
+#     Handles Indian transliteration phonetics (aspirated consonants, etc.)
+#     """
+#     if not name:
+#         return ""
+#     name = name.upper().strip()
+#     if not name:
+#         return ""
+
+#     # Pre-process: map aspirated/compound consonants to base
+#     for digraph, base in [("SH", "S"), ("PH", "F"), ("TH", "T"), ("DH", "D"),
+#                           ("KH", "K"), ("GH", "G"), ("BH", "B"), ("CH", "C"), ("JH", "J")]:
+#         name = name.replace(digraph, base)
+
+#     SOUNDEX_MAP = {
+#         'B': '1', 'F': '1', 'P': '1', 'V': '1', 'W': '1',
+#         'C': '2', 'G': '2', 'J': '2', 'K': '2', 'Q': '2', 'S': '2', 'X': '2', 'Z': '2',
+#         'D': '3', 'T': '3',
+#         'L': '4',
+#         'M': '5', 'N': '5',
+#         'R': '6',
+#     }
+
+#     code = name[0]
+#     prev_code = SOUNDEX_MAP.get(name[0], '0')
+
+#     for char in name[1:]:
+#         if char in 'AEIOUHY ':
+#             prev_code = '0'  # Reset on vowel/separator
+#             continue
+#         digit = SOUNDEX_MAP.get(char, '0')
+#         if digit != '0' and digit != prev_code:
+#             code += digit
+#             prev_code = digit
+
+#     return (code + '000')[:4]
+
+def indic_soundex_code(name: str) -> str:
+    """
+    Generate Indic Soundex code for a name token.
+    Handles Indian transliteration phonetics (aspirated consonants, etc.)
+    
+    [MODIFIED 2026-03-15] 
+    - Separated palatal fricatives (J, S, Z) from velars (K, G) in SOUNDEX_MAP to accurately 
+      penalize phonetically distinct names like Rajesh vs Rakesh.
+    """
+    if not name:
+        return ""
+    name = name.upper().strip()
+    if not name:
+        return ""
+
+    # Pre-process: map aspirated/compound consonants to base
+    for digraph, base in [("SH", "S"), ("PH", "F"), ("TH", "T"), ("DH", "D"),
+                          ("KH", "K"), ("GH", "G"), ("BH", "B"), ("CH", "C"), ("JH", "J")]:
+        name = name.replace(digraph, base)
+
+    SOUNDEX_MAP = {
+        'B': '1', 'F': '1', 'P': '1', 'V': '1', 'W': '1',
+        'C': '2', 'G': '2', 'K': '2', 'Q': '2', 'X': '2',
+        'D': '3', 'T': '3',
+        'L': '4',
+        'M': '5', 'N': '5',
+        'R': '6',
+        'J': '7', 'S': '7', 'Z': '7'
+    }
+
+    code = name[0]
+    prev_code = SOUNDEX_MAP.get(name[0], '0')
+
+    for char in name[1:]:
+        if char in 'AEIOUHY ':
+            prev_code = '0'  # Reset on vowel/separator
+            continue
+        digit = SOUNDEX_MAP.get(char, '0')
+        if digit != '0' and digit != prev_code:
+            code += digit
+            prev_code = digit
+
+    return (code + '000')[:4]
+
+
+def indic_soundex_similarity(text1: str, text2: str) -> float:
+    """
+    Compare two texts using Indic Soundex on each token.
+    Returns 0-100 similarity score.
+    """
+    tokens1 = text1.upper().split() if text1 else []
+    tokens2 = text2.upper().split() if text2 else []
+    if not tokens1 or not tokens2:
+        return 0.0
+
+    codes1 = [indic_soundex_code(t) for t in tokens1]
+    codes2 = [indic_soundex_code(t) for t in tokens2]
+
+    shorter, longer = (codes1, codes2) if len(codes1) <= len(codes2) else (codes2, codes1)
+    if not shorter:
+        return 0.0
+
+    total_match = 0.0
+    used = set()
+    for s_code in shorter:
+        best_match = 0.0
+        best_idx = -1
+        for i, l_code in enumerate(longer):
+            if i in used:
+                continue
+            match = sum(c1 == c2 for c1, c2 in zip(s_code, l_code)) / 4.0
+            if match > best_match:
+                best_match = match
+                best_idx = i
+        if best_idx >= 0:
+            used.add(best_idx)
+            total_match += best_match
+
+    return (total_match / len(shorter)) * 100
+
+# ---------- Core Matching Functions ----------
+def calculate_fuzzy_scores(input1: str, input2: str) -> Dict[str, float]:
+    """Calculate fuzzy matching scores using RapidFuzz (5 functions)"""
+    return {
+        "simple_ratio": fuzz.ratio(input1, input2),
+        "token_set_ratio": fuzz.token_set_ratio(input1, input2),
+        "w_ratio": fuzz.WRatio(input1, input2),
+        "partial_ratio": fuzz.partial_ratio(input1, input2),
+        "token_sort_ratio": fuzz.token_sort_ratio(input1, input2),
+    }
+
+def calculate_semantic_similarity(model_name: str, input1: str, input2: str) -> float:
+    """Calculate semantic similarity using sentence transformers"""
+    model = get_model(model_name)
+    # print("input1 to model",input1)
+    # print("input2 to model",input2)
+    embedding1 = model.encode([input1], show_progress_bar=False)
+    embedding2 = model.encode([input2], show_progress_bar=False)
+    
+    return cosine_similarity(embedding1, embedding2)[0][0]
+
+def calculate_final_score(fuzzy_scores: Dict[str, float], semantic_score: float) -> float:
+    """Calculate weighted final score"""
+    weights = MODEL_WEIGHTS
+    normalized_scores = {
+        "simple_ratio": fuzzy_scores.get("simple_ratio", 0),
+        "token_set_ratio": fuzzy_scores.get("token_set_ratio", 0),
+        "partial_ratio": fuzzy_scores.get("partial_ratio", 0),
+        "w_ratio": fuzzy_scores.get("w_ratio", 0),
+        "semantic_score": semantic_score * 100,
+    }
+    weighted_sum = sum(normalized_scores[key] * weight for key, weight in weights.items())
+    return max(0, min(100, weighted_sum))
+
+def calculate_overall_similarity(score1: float, score2: float) -> float:
+    """Calculate overall similarity from two model scores"""
+    return score1 * 0.6 + score2 * 0.4
+
+def check_substring_match(str1: str, str2: str) -> bool:
+    """Check if one string is a substring of another"""
+    if not str1 or not str2:
+        return False
+    return str1 in str2 or str2 in str1
+
+def check_individual_name_matches(name_full: str, fname: str, mname: str, lname: str) -> Tuple[bool, bool, bool]:
+    """
+    Check if full name contains first, middle, or last name as substring
+    Returns: (first_match, middle_match, last_match)
+    """
+    f_match = check_substring_match(name_full, fname) if fname else False
+    m_match = check_substring_match(name_full, mname) if mname else False
+    l_match = check_substring_match(name_full, lname) if lname else False
+    return f_match, m_match, l_match
+
+
+def concatenate_name_parts(firstname: str, middlename: str, lastname: str) -> str:
+    """Concatenate name parts"""
+    parts = []
+    if firstname and firstname not in ["-", " ", ""]:
+        parts.append(firstname.upper().strip())
+    if middlename and middlename not in ["-", " ", ""]:
+        parts.append(middlename.upper().strip())
+    if lastname and lastname not in ["-", " ", ""]:
+        parts.append(lastname.upper().strip())
+    
+    if not parts:
+        return ""
+    
+    parts.sort()
+    return " ".join(parts)
+
+# ---------- helpers used only inside the new logic ----------
+def _normalize_and_sort(name: str) -> str:
+    """
+    1. Split on any non-alphanumeric character (space, underscore, comma, etc.)
+    2. Remove empty tokens
+    3. Upper-case
+    4. Sort alphabetically
+    5. Re-join with single space
+    """
+    tokens = re.split(r'[^A-Za-z0-9]+', name.strip())
+    tokens = [t.upper() for t in tokens if t]
+    return ' '.join(sorted(tokens))
+
+def _all_name_combinations(fname: str, mname: str, lname: str) -> list[str]:
+    """
+    Return every possible ordering of the supplied parts,
+    dropping any empty/blank components.
+    """
+    parts = []
+    for p in (fname, mname, lname):
+        if p and p.strip() not in ('-', '', ' '):
+            parts.append(p.strip().upper())
+    if not parts:
+        return []
+    # itertools.permutations gives every ordering
+    return [' '.join(order) for order in itertools.permutations(parts)]
+
+
+# def match_entities(value1: str, value2: str, weights: Dict[str, float] = None) -> float:
+#     """
+#     Match two entities using fuzzy + semantic + optional phonetic similarity.
+#     Weights dict determines score component contributions.
+#     Returns: similarity score as float (0-100)
+#     """
+#     if weights is None:
+#         weights = MODEL_WEIGHTS
+
+#     standardized_input1 = preprocess_for_matching(value1)
+#     standardized_input2 = preprocess_for_matching(value2)
+
+#     if not standardized_input1 or not standardized_input2:
+#         return 0
+
+#     # Space-agnostic exact match
+#     if standardized_input1.replace(" ", "") == standardized_input2.replace(" ", ""):
+#         return 100.0
+
+#     return calculate_similarity_with_models(standardized_input1, standardized_input2, weights)
+
+def match_entities(value1: str, value2: str, weights: Dict[str, float] = None) -> float:
+    """
+    Match two entities using fuzzy + semantic + optional phonetic similarity.
+    Weights dict determines score component contributions.
+    
+    Handles:
+    1. Normal match          : "Pujitha Sharma"    vs "pujitha sharma"
+    2. Space-agnostic match  : "Pujitha Sharma"    vs "pujithasharma"
+    3. South Indian names    : "Sharma Gari Pujitha" vs "Pujitha Sharma Gari"
+                               (token order doesn't matter, combinations checked)
+    
+    Returns: similarity score as float (0-100)
+    
+    
+    - Integrated 'Check 3: Acronym / Initial expansion'. Matches acronyms to 
+      full names (e.g. K V Reddy vs Katta Venkata Reddy) and boosts to 90+. 
+      Penalizes mismatching initials (e.g. C Anitha vs H Anitha) by -40.
+    - Added 'Check 5: Final Phonetic Audit'. Uses Indic Soundex to securely 
+      escalate minor spelling variants (likitha vs likheetha) to 95+ and heavily 
+      punish mathematically close false-positives (rajesh vs rakesh).
+    """
+    if weights is None:
+        weights = MODEL_WEIGHTS
+
+    standardized_input1 = preprocess_for_matching(value1)
+    standardized_input2 = preprocess_for_matching(value2)
+
+    if not standardized_input1 or not standardized_input2:
+        return 0
+
+    # =========================================================
+    # CHECK 1: Space-agnostic exact match
+    # "Pujitha Sharma" vs "pujithasharma" → 100.0
+    # =========================================================
+    if standardized_input1.replace(" ", "") == standardized_input2.replace(" ", ""):
+        return 100.0
+
+    # =========================================================
+    # CHECK 2: Token-order permutation match (South Indian names)
+    # "sharmagari pujitha" vs "pujitha sharmagari" → 100.0
+    # Splits both names into tokens, checks if any permutation
+    # of tokens (joined with/without space) matches the other
+    # =========================================================
+    tokens1 = standardized_input1.split()
+    tokens2 = standardized_input2.split()
+
+    # Only attempt if token count is manageable (avoid factorial explosion)
+    if len(tokens1) <= 4 and len(tokens2) <= 4:
+
+        # Generate all permutations of tokens1 and check against tokens2 (space-agnostic)
+        target_nospace = standardized_input2.replace(" ", "")
+
+        for perm in itertools.permutations(tokens1):
+            # joined with space:    "pujitha sharmagari"
+            # joined without space: "pujithasharmagari"
+            perm_with_space    = " ".join(perm)
+            perm_without_space = "".join(perm)
+
+            if perm_with_space == standardized_input2:
+                return 100.0
+
+            if perm_without_space == target_nospace:
+                return 100.0
+
+        # Also check permutations of tokens2 against tokens1 (space-agnostic)
+        target_nospace1 = standardized_input1.replace(" ", "")
+
+        for perm in itertools.permutations(tokens2):
+            perm_with_space    = " ".join(perm)
+            perm_without_space = "".join(perm)
+
+            if perm_with_space == standardized_input1:
+                return 100.0
+
+            if perm_without_space == target_nospace1:
+                return 100.0
+
+    # =========================================================
+    # CHECK 3: Acronym / Initial expansion match or mismatch
+    # "K V Reddy" vs "Katta Venkata Reddy" → initial match → escalate to 90.0+
+    # "C Anitha" vs "H Anitha" → mismatched initials → severe penalty (-40.0)
+    # =========================================================
+    if len(tokens1) > 0 and len(tokens2) > 0:
+        common = set(tokens1) & set(tokens2)
+        rem1 = [t for t in tokens1 if t not in common]
+        rem2 = [t for t in tokens2 if t not in common]
+        
+        # Only apply if they share some tokens (like a last name) but differ in the rest
+        if common and rem1 and rem2:
+            rem1_is_initials = all(len(t) == 1 for t in rem1)
+            rem2_is_initials = all(len(t) == 1 for t in rem2)
+            
+            initials_list = None
+            fullcaps_list = None
+            
+            # Identify which is the initials array and which is the longer names array
+            if rem1_is_initials and not rem2_is_initials:
+                initials_list = rem1
+                fullcaps_list = rem2
+            elif rem2_is_initials and not rem1_is_initials:
+                initials_list = rem2
+                fullcaps_list = rem1
+            elif rem1_is_initials and rem2_is_initials:
+                # Both are just single letters! (e.g. C Anitha vs H Anitha)
+                initials_list = rem1
+                fullcaps_list = rem2
+
+            if initials_list is not None and fullcaps_list is not None:
+                initials_set = {t[0] for t in initials_list}
+                first_letters_set = {t[0] for t in fullcaps_list if t}
+                
+                # Check for intersection. If they map cleanly, escalate to 90
+                if initials_set == first_letters_set or initials_set.issubset(first_letters_set) or first_letters_set.issubset(initials_set):
+                    base_score = calculate_similarity_with_models(standardized_input1, standardized_input2, weights)
+                    return max(90.0, base_score)
+                else:
+                    # Explicit conflicting initials! (e.g., C vs H or K vs M)
+                    base_score = calculate_similarity_with_models(standardized_input1, standardized_input2, weights)
+                    return max(0.0, base_score - 40.0)
+            else:
+                # =========================================================
+                # EXPLICIT CONFLICTING CORE NAMES - 15-03-2026
+                # Example: "M. Manisha Reddy" vs "M. Manoj Reddy" -> Shared: M, Reddy. Unmatched: Manisha vs Manoj
+                # Example: "Mukherjee Lakshmi" vs "Prasad Lakshmi" -> Shared: Lakshmi. Unmatched: Mukherjee vs Prasad
+                # Since neither unmatched set are initials, evaluate them as explicit words
+                # =========================================================
+                rem1_str = " ".join(rem1)
+                rem2_str = " ".join(rem2)
+                
+                rem_fuzzy = fuzz.ratio(rem1_str, rem2_str)
+                if rem_fuzzy < 65.0:
+                    base_score = calculate_similarity_with_models(standardized_input1, standardized_input2, weights)
+                    # Severely penalize because key identifying words actively contradict each other
+                    return max(0.0, base_score - 40.0)
+
+    # =========================================================
+    # CHECK 4: Fallback → weighted model scoring
+    # "Pujitha Sharma" vs "Jon Smyth" → ~78.5 (fuzzy+semantic)
+    # =========================================================
+    base_score = calculate_similarity_with_models(standardized_input1, standardized_input2, weights)
+
+    # =========================================================
+    # CHECK 5: Final Phonetic Audit (for single words/names primarily)
+    # If they are single continuous names, check if they are identical 
+    # phonetically. If they are divergent, brutally penalize to prevent false positives.
+    # =========================================================
+    if len(tokens1) == 1 and len(tokens2) == 1:
+        ph_score = indic_soundex_similarity(standardized_input1, standardized_input2)
+        
+        # Phonetically identical but minor spelling difference (likitha vs likheetha) -> escalate to 95.0+
+        if ph_score == 100.0:
+            if fuzz.ratio(standardized_input1, standardized_input2) > 65 and abs(len(standardized_input1) - len(standardized_input2)) <= 2:
+                return max(95.0, base_score)
+        
+        # Highly distinct phonetics but mathematically close text (Rajesh vs Rakesh) -> ~50.0
+        elif ph_score <= 80.0:
+            if base_score > 55.0:
+                # heavily penalize false-positive anagrams/typos
+                return min(base_score - 25.0, 55.0)
+
+    return base_score
+
+# def calculate_similarity_with_models(text1: str, text2: str, weights: Dict[str, float] = None) -> float:
+#     """
+#     Calculate similarity using fuzzy scores, embedding models, and optional phonetic.
+#     The weights dict controls which components are active and their contribution.
+#     Phonetic components (jaro_winkler, indic_soundex) are used only if present in weights.
+#     Returns similarity percentage as float (0-100)
+#     """
+#     if weights is None:
+#         weights = MODEL_WEIGHTS
+
+#     if not text1 or not text2:
+#         print(f"[SIMILARITY] either value is empty — text1={text1!r} text2={text2!r}")
+#         return 0.0
+
+#     text1 = str(text1).strip()
+#     text2 = str(text2).strip()
+
+#     if not text1 or not text2:
+#         return 0.0
+
+#     print(f"[SIMILARITY] text1={text1!r}")
+#     print(f"[SIMILARITY] text2={text2!r}")
+
+#     # Space-agnostic exact match
+#     if text1.replace(" ", "") == text2.replace(" ", ""):
+#         return 100.0
+
+#     # --- Fuzzy scores (5 functions) ---
+#     fuzzy_scores = {
+#         "simple_ratio": fuzz.ratio(text1, text2),
+#         "token_set_ratio": fuzz.token_set_ratio(text1, text2),
+#         "w_ratio": fuzz.WRatio(text1, text2),
+#         "partial_ratio": fuzz.partial_ratio(text1, text2),
+#         "token_sort_ratio": fuzz.token_sort_ratio(text1, text2),
+#     }
+
+#     # --- Phonetic scores (only if weights include them) ---
+#     phonetic_scores = {}
+#     if weights.get("jaro_winkler", 0) > 0:
+#         phonetic_scores["jaro_winkler"] = JaroWinkler.similarity(text1, text2) * 100
+#     if weights.get("indic_soundex", 0) > 0:
+#         phonetic_scores["indic_soundex"] = indic_soundex_similarity(text1, text2)
+
+#     # --- Semantic scores (dual model, computed in parallel) ---
+#     with ThreadPoolExecutor() as executor:
+#         model1 = get_model("model1")
+#         model2 = get_model("model2")
+
+#         f1 = executor.submit(
+#             lambda: cosine_similarity(
+#                 model1.encode([text1], show_progress_bar=False),
+#                 model1.encode([text2], show_progress_bar=False)
+#             )[0][0]
+#         )
+#         f2 = executor.submit(
+#             lambda: cosine_similarity(
+#                 model2.encode([text1], show_progress_bar=False),
+#                 model2.encode([text2], show_progress_bar=False)
+#             )[0][0]
+#         )
+#         cosine1 = f1.result()
+#         cosine2 = f2.result()
+
+#     def calc_final(semantic_cosine):
+#         all_scores = {}
+#         all_scores.update(fuzzy_scores)
+#         all_scores.update(phonetic_scores)
+#         all_scores["semantic_score"] = semantic_cosine * 100
+#         return sum(all_scores.get(k, 0) * v for k, v in weights.items())
+
+#     final1 = calc_final(cosine1)
+#     final2 = calc_final(cosine2)
+
+#     overall_similarity = final1 * 0.6 + final2 * 0.4
+#     print("similarity given by model",overall_similarity)
+#     return round(max(0, min(100, overall_similarity)), 2)
+
+def calculate_similarity_with_models(text1: str, text2: str, weights: Dict[str, float] = None) -> float:
+    """
+    Calculate similarity using fuzzy scores, embedding models, and optional phonetic.
+    The weights dict controls which components are active and their contribution.
+    Phonetic components (jaro_winkler, indic_soundex) are used only if present in weights.
+    Returns similarity percentage as float (0-100)
+    """
+    if weights is None:
+        weights = MODEL_WEIGHTS
+
+    if not text1 or not text2:
+        return 0.0
+
+    text1 = str(text1).strip()
+    text2 = str(text2).strip()
+
+    if not text1 or not text2:
+        return 0.0
+
+    # Space-agnostic exact match
+    if text1.replace(" ", "") == text2.replace(" ", ""):
+        return 100.0
+
+    # --- Fuzzy scores (5 functions) ---
+    fuzzy_scores = {
+        "simple_ratio": fuzz.ratio(text1, text2),
+        "token_set_ratio": fuzz.token_set_ratio(text1, text2),
+        "w_ratio": fuzz.WRatio(text1, text2),
+        "partial_ratio": fuzz.partial_ratio(text1, text2),
+        "token_sort_ratio": fuzz.token_sort_ratio(text1, text2),
+    }
+
+    # --- Phonetic scores (only if weights include them) ---
+    phonetic_scores = {}
+    if weights.get("jaro_winkler", 0) > 0:
+        phonetic_scores["jaro_winkler"] = JaroWinkler.similarity(text1, text2) * 100
+    if weights.get("indic_soundex", 0) > 0:
+        phonetic_scores["indic_soundex"] = indic_soundex_similarity(text1, text2)
+
+    # --- Semantic scores (dual model, computed in parallel) ---
+    with ThreadPoolExecutor() as executor:
+        model1 = get_model("model1")
+        model2 = get_model("model2")
+
+        f1 = executor.submit(
+            lambda: cosine_similarity(
+                model1.encode([text1]),
+                model1.encode([text2])
+            )[0][0]
+        )
+        f2 = executor.submit(
+            lambda: cosine_similarity(
+                model2.encode([text1]),
+                model2.encode([text2])
+            )[0][0]
+        )
+        cosine1 = f1.result()
+        cosine2 = f2.result()
+
+    def calc_final(semantic_cosine):
+        all_scores = {}
+        all_scores.update(fuzzy_scores)
+        all_scores.update(phonetic_scores)
+        all_scores["semantic_score"] = semantic_cosine * 100
+        return sum(all_scores.get(k, 0) * v for k, v in weights.items())
+
+    final1 = calc_final(cosine1)
+    final2 = calc_final(cosine2)
+
+    overall_similarity = final1 * 0.6 + final2 * 0.4
+    return round(max(0, min(100, overall_similarity)), 2)
+
+# def handle_case1(full_name1: str, full_name2: str, 
+#                  r1_fname: str, r1_mname: str, r1_lname: str, 
+#                  r2_fname: str, r2_mname: str, r2_lname: str) -> dict:
+#     """
+#     Case-1 (both records supply a full name)
+#     Returns a dictionary with separate similarity scores for each component
+    
+#     Returns:
+#         dict: {
+#             'full_name_percent': float,  # full_name1 vs full_name2
+#             'firstname_percent': float,   # r1_fname vs r2_fname
+#             'middlename_percent': float,  # r1_mname vs r2_mname
+#             'lastname_percent': float     # r1_lname vs r2_lname
+#         }
+#     """
+#     result={}
+    
+#     # Check space-agnostic exact match on original strings before sorting
+#     if full_name1.replace(" ", "").upper() == full_name2.replace(" ", "").upper():
+#         full_name_percent = 100.0
+#     else:
+#         # 1. Normalize + alphabetically sort each full name and calculate similarity
+#         sorted1 = _normalize_and_sort(full_name1)
+#         sorted2 = _normalize_and_sort(full_name2)
+#         full_name_percent = calculate_similarity_with_models(sorted1, sorted2, NAME_MODEL_WEIGHTS)
+#     # print("full_name_percent is:",full_name_percent)
+    
+#     # 2. Calculate firstname_percent: compare firstnames
+#    # firstname
+#     if r1_fname and r2_fname:
+#         firstname_percent = calculate_similarity_with_models(
+#             r1_fname, r2_fname, NAME_MODEL_WEIGHTS
+#         )
+#         # print("firstname_percent is:",firstname_percent)
+#     else:
+#         firstname_percent = 0.0
+
+#     # middlename
+#     if r1_mname and r2_mname:
+#         middlename_percent = calculate_similarity_with_models(
+#             r1_mname, r2_mname, NAME_MODEL_WEIGHTS
+#         )
+#         # print("middlename_percent is:",middlename_percent)
+#     else:
+#         middlename_percent = 0.0
+
+#     # lastname
+#     if r1_lname and r2_lname:
+#         lastname_percent = calculate_similarity_with_models(
+#             r1_lname, r2_lname, NAME_MODEL_WEIGHTS
+#         )
+#         # print("lastname_percent is:",lastname_percent)
+#     else:
+#         lastname_percent = 0.0
+
+        
+
+#     result={
+#         'full_name_percent': full_name_percent,
+#         'firstname_percent': firstname_percent,
+#         'middlename_percent': middlename_percent,
+#         'lastname_percent': lastname_percent
+#     }
+#     return result
+
+# def handle_case2(full_name: str,
+#                  fname: str, mname: str, lname: str,
+#                  concat_name: str) -> dict:
+#     """
+#     Case-2 (one side has full name, the other has F/M/L)
+#     Returns a dictionary with separate similarity scores for each component
+    
+#     Returns:
+#         dict: {
+#             'full_name_percent': float,  # full_name vs concat_name
+#             'firstname_percent': float,   # full_name vs fname
+#             'middlename_percent': float,  # full_name vs mname
+#             'lastname_percent': float     # full_name vs lname
+#         }
+#     """
+#     # 0. Check if any permutation of F/M/L exactly reconstructs full_name.
+#     # If yes, full_name_percent = 100. Component scores are still computed
+#     # individually — a part inside full_name does NOT score 100% on its own.
+#     # e.g. full_name="KALLI LIKHITHA", fname="KALLI", mname="LIKHITHA":
+#     #   full_name_percent = 100 (together they reconstruct it exactly)
+#     #   firstname_percent != 100 ("KALLI" is only half of "KALLI LIKHITHA")
+#     permutation_full_match = any(
+#         permuted.replace(" ", "") == full_name.upper().strip().replace(" ", "")
+#         for permuted in _all_name_combinations(fname, mname, lname)
+#     )
+
+#     # 1. Calculate full_name_percent
+#     if permutation_full_match:
+#         full_name_percent = 100.0
+#     else:
+#         sorted_full = _normalize_and_sort(full_name)
+#         sorted_concat = _normalize_and_sort(concat_name)
+#         full_name_percent = calculate_similarity_with_models(
+#             sorted_full,
+#             sorted_concat,
+#             NAME_MODEL_WEIGHTS
+#         )
+
+#     # Component-level scores: compare full_name vs each individual part (fname/mname/lname).
+#     #
+#     # Requirement:
+#     #   - full_name="KALLI LIKHITHA", fname="KALLI" → firstname_percent reflects
+#     #     how well "KALLI" matches within the context of the full name, but must
+#     #     NOT be 100% just because "KALLI" is a complete subset of "KALLI LIKHITHA".
+#     #   - The comparison is full_name vs part (not token-to-token), so the full
+#     #     context of the name is preserved.
+#     #
+#     # Why standard weights fail:
+#     #   - partial_ratio("KALLI LIKHITHA", "KALLI") = 100  ← subset inflation
+#     #   - token_set_ratio produces same inflation
+#     #   - w_ratio picks the best of these → also inflated
+#     #   - semantic embeddings: short name vs full name share high cosine similarity
+#     #     because they encode overlapping meaning → also inflated
+#     #
+#     # Fix: use only LENGTH-SENSITIVE metrics that naturally penalise length
+#     # disparity between the strings.
+#     #   - simple_ratio:  2 * matches / total_chars  — drops when lengths differ
+#     #   - jaro_winkler:  character-overlap with length normalisation — same
+#     #   - indic_soundex: phonetic token overlap / shorter length — same
+#     # Intentionally excluded: partial_ratio, token_set_ratio, w_ratio, semantic.
+
+#     _COMPONENT_WEIGHTS = {
+#         "simple_ratio":  0.35,
+#         "jaro_winkler":  0.40,
+#         "indic_soundex": 0.25,
+#     }
+
+#     def _fullname_vs_part(full: str, part: str) -> float:
+#         """
+#         Compare full_name against a single name part using only length-sensitive
+#         metrics. Returns 0-100. A part that is a strict subset of full_name will
+#         score proportionally to how much of the full_name it covers, not 100%.
+#         """
+#         if not full or not part:
+#             return 0.0
+#         full_u = full.upper().strip()
+#         part_u = part.upper().strip()
+#         if full_u == part_u:
+#             return 100.0
+#         scores = {
+#             "simple_ratio":  fuzz.ratio(full_u, part_u),
+#             "jaro_winkler":  JaroWinkler.similarity(full_u, part_u) * 100,
+#             "indic_soundex": indic_soundex_similarity(full_u, part_u),
+#         }
+#         return round(max(0.0, min(100.0,
+#             sum(scores[k] * v for k, v in _COMPONENT_WEIGHTS.items())
+#         )), 2)
+
+#     # 2. firstname_percent: full_name vs fname
+#     firstname_percent  = _fullname_vs_part(full_name, fname)  if fname else 0.0
+#     # 3. middlename_percent: full_name vs mname
+#     middlename_percent = _fullname_vs_part(full_name, mname) if mname else 0.0
+#     # 4. lastname_percent: full_name vs lname
+#     lastname_percent   = _fullname_vs_part(full_name, lname) if (lname and lname.upper() not in SURNAME_IDENTIFIER) else 0.0
+
+#     result={
+#         'full_name_percent': full_name_percent,
+#         'firstname_percent': firstname_percent,
+#         'middlename_percent': middlename_percent,
+#         'lastname_percent': lastname_percent
+#     }
+#     return result
+
+
+# def handle_case3(r1_fname: str, r1_mname: str, r1_lname: str, r1_concat: str,
+#                  r2_fname: str, r2_mname: str, r2_lname: str, r2_concat: str) -> dict:
+#     """
+#     Handle Case 3: Both records have F/M/L
+#     Returns a dictionary with separate similarity scores for each component
+    
+#     Returns:
+#         dict: {
+#             'full_name_percent': float,  # r1_concat vs r2_concat
+#             'firstname_percent': float,   # r1_fname vs r2_fname
+#             'middlename_percent': float,  # r1_mname vs r2_mname
+#             'lastname_percent': float     # r1_lname vs r2_lname
+#         }
+#     """
+#     # Check substring matches for each component
+#     f_match = check_substring_match(r1_fname, r2_fname) if r1_fname and r2_fname else False
+#     m_match = check_substring_match(r1_mname, r2_mname) if r1_mname and r2_mname else False
+#     l_match = check_substring_match(r1_lname, r2_lname) if r1_lname and r2_lname else False
+    
+#     # Calculate full_name_percent: compare concatenated names
+#     full_name_percent = calculate_similarity_with_models(r1_concat, r2_concat, NAME_MODEL_WEIGHTS)
+    
+#     # Apply boosting logic based on substring matches
+#     # Rule 1: Only lastname matches (family match)
+#     if l_match and not f_match and not m_match:
+#         full_name_percent = max(full_name_percent, 85.0)  # Ensure minimum 85% for family match
+    
+#     # Rule 2: Lastname + (firstname or middle) matches (partial match)
+#     # Strong indicator of same person
+#     elif l_match and (f_match or m_match):
+#         full_name_percent = max(full_name_percent, 90.0)  # Higher confidence when lastname + another field matches
+    
+#     # Rule 3: No matches at all or only firstname/middlename matches
+#     # Use the calculated similarity as-is
+    
+#     # Calculate individual component percentages
+#     # 2. Calculate firstname_percent: compare firstnames
+#     if r1_fname and r2_fname:
+#         firstname_percent = calculate_similarity_with_models(
+#             r1_fname, 
+#             r2_fname,
+#             NAME_MODEL_WEIGHTS
+#         )  
+#     else:
+#         firstname_percent=0.0
+
+#     # 3. Calculate middlename_percent: compare middlenames
+#     if r1_mname and r2_mname:
+#         middlename_percent = calculate_similarity_with_models(
+#             r1_mname, 
+#             r2_mname,
+#             NAME_MODEL_WEIGHTS
+#         )  
+#     else:
+#         middlename_percent=0.0
+
+#     # 4. Calculate lastname_percent: compare lastnames
+#     if r1_lname and r2_lname and r1_lname.upper() not in SURNAME_IDENTIFIER and r2_lname.upper() not in SURNAME_IDENTIFIER:
+#         lastname_percent = calculate_similarity_with_models(
+#             r1_lname, 
+#             r2_lname,
+#             NAME_MODEL_WEIGHTS
+#         )  
+#     else:
+#         lastname_percent=0.0
+
+#     result= {
+#         'full_name_percent': full_name_percent,
+#         'firstname_percent': firstname_percent,
+#         'middlename_percent': middlename_percent,
+#         'lastname_percent': lastname_percent
+#     }
+#     return result
+
+# def match_name(name: str, firstname: str, lastname: str, middlename: str) -> float:
+#     """
+#     Match name with logic
+#     Returns similarity score as float or "missing value"
+#     """
+#     name_processed = preprocess_for_matching(name)
+#     concat_name = concatenate_name_parts(firstname, middlename, lastname)
+    
+#     # Case 1: NAME matches concatenated name
+#     if name_processed and concat_name and name_processed == concat_name:
+#         return 100
+    
+#     # Case 2: NAME is empty, use concatenated
+#     if not name_processed and concat_name:
+#         return 100
+    
+#     # Case 3: Concat is empty, use NAME
+#     if name_processed and not concat_name:
+#         return 100 
+    
+#     # Case 4: Both exist but different - use model
+#     if name_processed and concat_name and name_processed != concat_name:
+#         # Pass both to model for fuzzy matching
+#         return match_entities(name_processed, concat_name)
+    
+#     # Both empty
+#     return 0
+
+# def match_names_cross_records(r1_name: str, r1_firstname: str, r1_lastname: str, r1_middlename: str,
+#                                r2_name: str, r2_firstname: str, r2_lastname: str, r2_middlename: str) -> float:
+#     """
+#     Match names between two records with enhanced preprocessing:
+#     1. Input is already lowercase + preprocessed (titles removed, variations standardized)
+#     2. Surname detection — if only common surnames match, return 20%
+#     3. Token sorting for consistent comparison
+#     4. Common token detection
+#     5. Initial letter boost for abbreviated names
+#     6. Three-case matching (both fullname / one fullname+FML / both FML)
+#     """
+#     # ── Normalize inputs (already lowercase from preprocess_name) ──
+#     r1_name_proc = r1_name.strip() if r1_name and r1_name.strip() not in ["-", ""] else ""
+#     r2_name_proc = r2_name.strip() if r2_name and r2_name.strip() not in ["-", ""] else ""
+
+#     r1_fname = r1_firstname.strip() if r1_firstname and r1_firstname.strip() not in ["-", ""] else ""
+#     r1_mname = r1_middlename.strip() if r1_middlename and r1_middlename.strip() not in ["-", ""] else ""
+#     r1_lname = r1_lastname.strip() if r1_lastname and r1_lastname.strip() not in ["-", ""] else ""
+
+#     r2_fname = r2_firstname.strip() if r2_firstname and r2_firstname.strip() not in ["-", ""] else ""
+#     r2_mname = r2_middlename.strip() if r2_middlename and r2_middlename.strip() not in ["-", ""] else ""
+#     r2_lname = r2_lastname.strip() if r2_lastname and r2_lastname.strip() not in ["-", ""] else ""
+
+#     # ── Determine case ──
+#     r1_has_fullname = bool(r1_name_proc)
+#     r2_has_fullname = bool(r2_name_proc)
+
+#     r1_concat = concatenate_name_parts(r1_fname, r1_mname, r1_lname).lower()
+#     r2_concat = concatenate_name_parts(r2_fname, r2_mname, r2_lname).lower()
+
+#     # Build the effective full name string for each record
+#     name1_effective = r1_name_proc if r1_has_fullname else r1_concat
+#     name2_effective = r2_name_proc if r2_has_fullname else r2_concat
+
+#     # Both missing → zero
+#     if not name1_effective and not name2_effective:
+#         return {
+#             'full_name_percent': 0.0,
+#             'firstname_percent': 0.0,
+#             'middlename_percent': 0.0,
+#             'lastname_percent': 0.0
+#         }
+
+#     # ── Accumulate adjustments (applied AFTER handle_case computation) ──
+#     adjustment = 0
+#     surname_penalty_val = NAME_MATCH_ADJUSTMENTS.get("surname_penalty", -30)
+#     initial_boost_val = NAME_MATCH_ADJUSTMENTS.get("initial_boost", 30)
+#     subset_boost_val = NAME_MATCH_ADJUSTMENTS.get("subset_boost", 40)
+
+#     # ── Surname detection (case 2): penalty if surname-only match ──
+#     surname_only_match = False
+#     if name1_effective and name2_effective:
+#         surnames1 = detect_surnames(name1_effective)
+#         surnames2 = detect_surnames(name2_effective)
+
+#         if surnames1 and surnames2:
+#             common_surnames = surnames1 & surnames2
+#             if common_surnames:
+#                 tokens1_non_surname = [t for t in name1_effective.split() if t not in surnames1]
+#                 tokens2_non_surname = [t for t in name2_effective.split() if t not in surnames2]
+
+#                 if tokens1_non_surname and tokens2_non_surname:
+#                     non_surname_overlap = set(tokens1_non_surname) & set(tokens2_non_surname)
+#                     if not non_surname_overlap:
+#                         non_surname1_str = " ".join(tokens1_non_surname)
+#                         non_surname2_str = " ".join(tokens2_non_surname)
+#                         if fuzz.ratio(non_surname1_str, non_surname2_str) < 60:
+#                             surname_only_match = True
+#                             adjustment += surname_penalty_val  # e.g., -30
+
+#     # ── Sort tokens for boost/subset detection ──
+#     name1_tokens = sorted(name1_effective.split()) if name1_effective else []
+#     name2_tokens = sorted(name2_effective.split()) if name2_effective else []
+
+#     # ── Initial letter boost / mismatch penalty (Case 3A) ──
+#     # compute_initial_letter_boost returns:
+#     #   +0.2 → all initials matched  → add initial_boost_val (+10.5)
+#     #   -0.2 → at least one initial did NOT match → subtract initial_boost_val (-10.5)
+#     #    0.0 → no initials present → no change
+#     if name1_tokens and name2_tokens:
+#         boost = compute_initial_letter_boost(name1_tokens, name2_tokens)
+#         if boost > 0:
+#             adjustment += initial_boost_val    # initials matched  → boost
+#         elif boost < 0:
+#             adjustment -= initial_boost_val    # initials mismatched → penalty
+
+#     # ── Subset match boost (case 5): +40 if one is complete subset ──
+#     if name1_tokens and name2_tokens and len(name1_tokens) != len(name2_tokens):
+#         if is_subset_match(name1_tokens, name2_tokens):
+#             adjustment += subset_boost_val  # e.g., +40
+
+#     # ── Run the appropriate case handler for base similarity ──
+#     result = None
+
+#     # CASE 1: Both records have full names
+#     if r1_has_fullname and r2_has_fullname:
+#         result = handle_case1(r1_name_proc, r2_name_proc,
+#                               r1_firstname, r1_middlename, r1_lastname,
+#                               r2_firstname, r2_middlename, r2_lastname)
+
+#     # CASE 2: One has full name, other has F/M/L
+#     elif r1_has_fullname and not r2_has_fullname and r2_concat:
+#         result = handle_case2(r1_name_proc, r2_fname, r2_mname, r2_lname, r2_concat)
+
+#     elif r2_has_fullname and not r1_has_fullname and r1_concat:
+#         result = handle_case2(r2_name_proc, r1_fname, r1_mname, r1_lname, r1_concat)
+
+#     # CASE 3: Both have F/M/L
+#     elif not r1_has_fullname and not r2_has_fullname and r1_concat and r2_concat:
+#         result = handle_case3(r1_fname, r1_mname, r1_lname, r1_concat,
+#                               r2_fname, r2_mname, r2_lname, r2_concat)
+
+#     # Fallback if no case matched
+#     if result is None:
+#         result = {
+#             'full_name_percent': 0.0,
+#             'firstname_percent': 0.0,
+#             'middlename_percent': 0.0,
+#             'lastname_percent': 0.0
+#         }
+
+#     # ── Apply accumulated adjustments to full_name_percent ──
+#     if adjustment != 0:
+#         result['full_name_percent'] = max(0.0, min(100.0, result['full_name_percent'] + adjustment))
+
+#     return result
+def handle_case1(full_name1: str, full_name2: str, 
+                 r1_fname: str, r1_mname: str, r1_lname: str, 
+                 r2_fname: str, r2_mname: str, r2_lname: str) -> dict:
+    """
+    Case-1 (both records supply a full name)
+    Returns a dictionary with separate similarity scores for each component
+    
+    Returns:
+        dict: {
+            'full_name_percent': float,  # full_name1 vs full_name2
+            'firstname_percent': float,   # r1_fname vs r2_fname
+            'middlename_percent': float,  # r1_mname vs r2_mname
+            'lastname_percent': float     # r1_lname vs r2_lname
+        }
+    """
+    result={}
+    
+    # Check space-agnostic exact match on original strings before sorting
+    if full_name1.replace(" ", "").upper() == full_name2.replace(" ", "").upper():
+        full_name_percent = 100.0
+    else:
+        # 1. Normalize + alphabetically sort each full name and calculate similarity
+        sorted1 = _normalize_and_sort(full_name1)
+        sorted2 = _normalize_and_sort(full_name2)
+        full_name_percent = match_entities(sorted1, sorted2, NAME_MODEL_WEIGHTS)
+    # print("full_name_percent is:",full_name_percent)
+    
+    # 2. Calculate firstname_percent: compare firstnames
+   # firstname
+    if r1_fname and r2_fname:
+        firstname_percent = match_entities(
+            r1_fname, r2_fname, NAME_MODEL_WEIGHTS
+        )
+        # print("firstname_percent is:",firstname_percent)
+    else:
+        firstname_percent = 0.0
+
+    # middlename
+    if r1_mname and r2_mname:
+        middlename_percent = match_entities(
+            r1_mname, r2_mname, NAME_MODEL_WEIGHTS
+        )
+        # print("middlename_percent is:",middlename_percent)
+    else:
+        middlename_percent = 0.0
+
+    # lastname
+    if r1_lname and r2_lname:
+        lastname_percent = match_entities(
+            r1_lname, r2_lname, NAME_MODEL_WEIGHTS
+        )
+        # print("lastname_percent is:",lastname_percent)
+    else:
+        lastname_percent = 0.0
+
+        
+
+    result={
+        'full_name_percent': full_name_percent,
+        'firstname_percent': firstname_percent,
+        'middlename_percent': middlename_percent,
+        'lastname_percent': lastname_percent
+    }
+    return result
+
+def handle_case2(full_name: str,
+                 fname: str, mname: str, lname: str,
+                 concat_name: str) -> dict:
+    """
+    Case-2 (one side has full name, the other has F/M/L)
+    Returns a dictionary with separate similarity scores for each component
+    
+    Returns:
+        dict: {
+            'full_name_percent': float,  # full_name vs concat_name
+            'firstname_percent': float,   # full_name vs fname
+            'middlename_percent': float,  # full_name vs mname
+            'lastname_percent': float     # full_name vs lname
+        }
+    """
+    # 0. Try every permutation of F/M/L
+    full_name_percent = None
+    for permuted in _all_name_combinations(fname, mname, lname):
+        if permuted.replace(" ", "") == full_name.upper().strip().replace(" ", ""):
+            # Perfect match for the Full Name component
+            full_name_percent = 100.0
+            break
+
+    # 1. Calculate full_name_percent: compare sorted components if exact match failed
+    if full_name_percent is None:
+        sorted_full = _normalize_and_sort(full_name)
+        sorted_concat = _normalize_and_sort(concat_name)
+        
+        full_name_percent = match_entities(
+            sorted_full, 
+            sorted_concat,
+            NAME_MODEL_WEIGHTS
+        )
+
+    # 2. Calculate firstname_percent: compare full_name with firstname only
+    if fname :
+        firstname_percent = match_entities(
+            full_name, 
+            fname,
+            NAME_MODEL_WEIGHTS
+        ) 
+    else:
+        firstname_percent=0.0
+    # 3. Calculate middlename_percent: compare full_name with middlename only
+    if mname :
+        middlename_percent = match_entities(
+            full_name, 
+            mname,
+            NAME_MODEL_WEIGHTS
+    )  
+    else:
+        middlename_percent=0.0
+
+    # 4. Calculate lastname_percent: compare full_name with lastname only
+    if lname and lname.upper() not in SURNAME_IDENTIFIER:
+        lastname_percent = match_entities(
+            full_name, 
+            lname,
+            NAME_MODEL_WEIGHTS
+    )  
+    else:
+        lastname_percent=0.0
+
+    result={
+        'full_name_percent': full_name_percent,
+        'firstname_percent': firstname_percent,
+        'middlename_percent': middlename_percent,
+        'lastname_percent': lastname_percent
+    }
+    return result
+
+
+def handle_case3(r1_fname: str, r1_mname: str, r1_lname: str, r1_concat: str,
+                 r2_fname: str, r2_mname: str, r2_lname: str, r2_concat: str) -> dict:
+    """
+    Handle Case 3: Both records have F/M/L
+    Returns a dictionary with separate similarity scores for each component
+    
+    Returns:
+        dict: {
+            'full_name_percent': float,  # r1_concat vs r2_concat
+            'firstname_percent': float,   # r1_fname vs r2_fname
+            'middlename_percent': float,  # r1_mname vs r2_mname
+            'lastname_percent': float     # r1_lname vs r2_lname
+        }
+    """
+    # Check substring matches for each component
+    f_match = check_substring_match(r1_fname, r2_fname) if r1_fname and r2_fname else False
+    m_match = check_substring_match(r1_mname, r2_mname) if r1_mname and r2_mname else False
+    l_match = check_substring_match(r1_lname, r2_lname) if r1_lname and r2_lname else False
+    
+    # Calculate full_name_percent: compare concatenated names
+    full_name_percent = match_entities(r1_concat, r2_concat, NAME_MODEL_WEIGHTS)
+    
+    # Apply boosting logic based on substring matches
+    # Rule 1: Only lastname matches (family match)
+    if l_match and not f_match and not m_match:
+        full_name_percent = max(full_name_percent, 85.0)  # Ensure minimum 85% for family match
+    
+    # Rule 2: Lastname + (firstname or middle) matches (partial match)
+    # Strong indicator of same person
+    elif l_match and (f_match or m_match):
+        full_name_percent = max(full_name_percent, 90.0)  # Higher confidence when lastname + another field matches
+    
+    # Rule 3: No matches at all or only firstname/middlename matches
+    # Use the calculated similarity as-is
+    
+    # 2. Calculate firstname_percent: compare firstnames
+    if r1_fname and r2_fname:
+        firstname_percent = match_entities(
+            r1_fname, 
+            r2_fname,
+            NAME_MODEL_WEIGHTS
+        )  
+    else:
+        firstname_percent=0.0
+
+    # 3. Calculate middlename_percent: compare middlenames
+    if r1_mname and r2_mname:
+        middlename_percent = match_entities(
+            r1_mname, 
+            r2_mname,
+            NAME_MODEL_WEIGHTS
+        )  
+    else:
+        middlename_percent=0.0
+
+    # 4. Calculate lastname_percent: compare lastnames
+    if r1_lname and r2_lname and r1_lname.upper() not in SURNAME_IDENTIFIER and r2_lname.upper() not in SURNAME_IDENTIFIER:
+        lastname_percent = match_entities(
+            r1_lname, 
+            r2_lname,
+            NAME_MODEL_WEIGHTS
+        )  
+    else:
+        lastname_percent=0.0
+
+    result= {
+        'full_name_percent': full_name_percent,
+        'firstname_percent': firstname_percent,
+        'middlename_percent': middlename_percent,
+        'lastname_percent': lastname_percent
+    }
+    return result
+
+def match_name(name: str, firstname: str, lastname: str, middlename: str) -> float:
+    """
+    Match name with logic
+    Returns similarity score as float or "missing value"
+    """
+    name_processed = preprocess_for_matching(name)
+    concat_name = concatenate_name_parts(firstname, middlename, lastname)
+    
+    # Case 1: NAME matches concatenated name
+    if name_processed and concat_name and name_processed == concat_name:
+        return 100
+    
+    # Case 2: NAME is empty, use concatenated
+    if not name_processed and concat_name:
+        return 100
+    
+    # Case 3: Concat is empty, use NAME
+    if name_processed and not concat_name:
+        return 100 
+    
+    # Case 4: Both exist but different - use model
+    if name_processed and concat_name and name_processed != concat_name:
+        # Pass both to model for fuzzy matching
+        return match_entities(name_processed, concat_name)
+    
+    # Both empty
+    return 0
+
+def match_names_cross_records(r1_name: str, r1_firstname: str, r1_lastname: str, r1_middlename: str,
+                               r2_name: str, r2_firstname: str, r2_lastname: str, r2_middlename: str) -> float:
+    """
+    Match names between two records with enhanced preprocessing:
+    1. Input is already lowercase + preprocessed (titles removed, variations standardized)
+    2. Surname detection — if only common surnames match, return 20%
+    3. Token sorting for consistent comparison
+    4. Common token detection
+    5. Initial letter boost for abbreviated names
+    6. Three-case matching (both fullname / one fullname+FML / both FML)
+    
+    [MODIFIED 2026-03-15]
+    - Refactored handle_case functions to properly pass exact permutation checking 
+      down to match_entities() instead of bypassing it to ml models.
+    - Updated handle_case2 exact match checker to cleanly yield the first, middle, 
+      and last name proportions instead of assuming 100% across the board.
+    - Implemented a -40 explicit penalty if two recognized surnames are detected 
+      but contradict each other completely (e.g. Krishna Rajput vs Krishna Singh).
+    """
+    # ── Normalize inputs (already lowercase from preprocess_name) ──
+    r1_name_proc = r1_name.strip() if r1_name and r1_name.strip() not in ["-", ""] else ""
+    r2_name_proc = r2_name.strip() if r2_name and r2_name.strip() not in ["-", ""] else ""
+
+    r1_fname = r1_firstname.strip() if r1_firstname and r1_firstname.strip() not in ["-", ""] else ""
+    r1_mname = r1_middlename.strip() if r1_middlename and r1_middlename.strip() not in ["-", ""] else ""
+    r1_lname = r1_lastname.strip() if r1_lastname and r1_lastname.strip() not in ["-", ""] else ""
+
+    r2_fname = r2_firstname.strip() if r2_firstname and r2_firstname.strip() not in ["-", ""] else ""
+    r2_mname = r2_middlename.strip() if r2_middlename and r2_middlename.strip() not in ["-", ""] else ""
+    r2_lname = r2_lastname.strip() if r2_lastname and r2_lastname.strip() not in ["-", ""] else ""
+
+    # ── Determine case ──
+    r1_has_fullname = bool(r1_name_proc)
+    r2_has_fullname = bool(r2_name_proc)
+
+    r1_concat = concatenate_name_parts(r1_fname, r1_mname, r1_lname).lower()
+    r2_concat = concatenate_name_parts(r2_fname, r2_mname, r2_lname).lower()
+
+    # Build the effective full name string for each record
+    name1_effective = r1_name_proc if r1_has_fullname else r1_concat
+    name2_effective = r2_name_proc if r2_has_fullname else r2_concat
+
+    # Both missing → zero
+    if not name1_effective and not name2_effective:
+        return {
+            'full_name_percent': 0.0,
+            'firstname_percent': 0.0,
+            'middlename_percent': 0.0,
+            'lastname_percent': 0.0
+        }
+
+    # ── Accumulate adjustments (applied AFTER handle_case computation) ──
+    adjustment = 0
+    surname_penalty_val = NAME_MATCH_ADJUSTMENTS.get("surname_penalty", -30)
+    initial_boost_val = NAME_MATCH_ADJUSTMENTS.get("initial_boost", 30)
+    subset_boost_val = NAME_MATCH_ADJUSTMENTS.get("subset_boost", 40)
+
+    # ── Surname detection (case 2): penalty if surname-only match ──
+    surname_only_match = False
+    if name1_effective and name2_effective:
+        surnames1 = detect_surnames(name1_effective)
+        surnames2 = detect_surnames(name2_effective)
+
+        if surnames1 and surnames2:
+            common_surnames = surnames1 & surnames2
+            if common_surnames:
+                tokens1_non_surname = [t for t in name1_effective.split() if t not in surnames1]
+                tokens2_non_surname = [t for t in name2_effective.split() if t not in surnames2]
+
+                if tokens1_non_surname and tokens2_non_surname:
+                    non_surname_overlap = set(tokens1_non_surname) & set(tokens2_non_surname)
+                    if not non_surname_overlap:
+                        non_surname1_str = " ".join(tokens1_non_surname)
+                        non_surname2_str = " ".join(tokens2_non_surname)
+                        if fuzz.ratio(non_surname1_str, non_surname2_str) < 60:
+                            surname_only_match = True
+                            adjustment += surname_penalty_val  # e.g., -30
+            else:
+                # Mismatching surnames! Both have a known surname, but they don't match.
+                # Example: "krishna rajput" vs "krishna singh" 
+                adjustment -= 40  # severe penalty for conflicting standard surnames
+
+    # ── Sort tokens for boost/subset detection ──
+    name1_tokens = sorted(name1_effective.split()) if name1_effective else []
+    name2_tokens = sorted(name2_effective.split()) if name2_effective else []
+
+    # ── Initial letter boost (case 4): +30 if initials match ──
+    if name1_tokens and name2_tokens:
+        boost = compute_initial_letter_boost(name1_tokens, name2_tokens)
+        if boost > 0:
+            adjustment += initial_boost_val  # e.g., +30
+
+    # ── Subset match boost (case 5): +40 if one is complete subset ──
+    if name1_tokens and name2_tokens and len(name1_tokens) != len(name2_tokens):
+        if is_subset_match(name1_tokens, name2_tokens):
+            adjustment += subset_boost_val  # e.g., +40
+
+    # ── Run the appropriate case handler for base similarity ──
+    result = None
+
+    # CASE 1: Both records have full names
+    if r1_has_fullname and r2_has_fullname:
+        result = handle_case1(r1_name_proc, r2_name_proc,
+                              r1_firstname, r1_middlename, r1_lastname,
+                              r2_firstname, r2_middlename, r2_lastname)
+
+    # CASE 2: One has full name, other has F/M/L
+    elif r1_has_fullname and not r2_has_fullname and r2_concat:
+        result = handle_case2(r1_name_proc, r2_fname, r2_mname, r2_lname, r2_concat)
+
+    elif r2_has_fullname and not r1_has_fullname and r1_concat:
+        result = handle_case2(r2_name_proc, r1_fname, r1_mname, r1_lname, r1_concat)
+
+    # CASE 3: Both have F/M/L
+    elif not r1_has_fullname and not r2_has_fullname and r1_concat and r2_concat:
+        result = handle_case3(r1_fname, r1_mname, r1_lname, r1_concat,
+                              r2_fname, r2_mname, r2_lname, r2_concat)
+
+    # Fallback if no case matched
+    if result is None:
+        result = {
+            'full_name_percent': 0.0,
+            'firstname_percent': 0.0,
+            'middlename_percent': 0.0,
+            'lastname_percent': 0.0
+        }
+
+    # ── Apply accumulated adjustments to full_name_percent ──
+    if adjustment != 0:
+        result['full_name_percent'] = max(0.0, min(100.0, result['full_name_percent'] + adjustment))
+
+    return result
+
+def match_addresses_1_to_n(addresses_r1: List[str], addresses_r2: List[str]) -> float:
+    """
+    Match addresses 1:N (plain addressline strings only — no city/zipcode/state).
+
+    Pipeline:
+      1. Extract all address components (house_no, flat, apartment, street) from each address
+      2. Pass remaining address (components removed) to embedding model → base_score
+      3. If base_score > 60: apply per-component boost/penalty
+           house_number : match +30 / mismatch -30
+           flat_number  : match +10 / mismatch -10
+           apartment    : match +10 / mismatch -10
+           street       : match +10 / mismatch -10
+         If base_score <= 60: skip all component adjustments
+      4. Named component + post-box adjustments
+      5. Cap final score to [0, 100]
+    """
+    from services.rules import (
+        preprocess_address           as _preprocess_addr,
+        compare_named_components     as _compare_named,
+        compare_postbox              as _compare_postbox,
+        remove_postbox_from_address  as _strip_postbox,
+        extract_address_components   as _extract_components,
+    )
+
+    def _norm(val):
+        """Strip all non-alphanumerics — 144/143 → 144143."""
+        if not val:
+            return ""
+        return re.sub(r'[^A-Z0-9]', '', str(val).upper())
+
+    def _component_adj(v1, v2, boost, penalty):
+        """Return (verdict, adjustment) for a single component pair."""
+        if v1 and v2:
+            return ("match", boost) if v1 == v2 else ("mismatch", -penalty)
+        return ("missing", 0.0)
+
+    raw1 = [a for a in addresses_r1 if a and str(a).strip() not in ["-", " ", ""]]
+    raw2 = [a for a in addresses_r2 if a and str(a).strip() not in ["-", " ", ""]]
+
+    if not raw1 or not raw2:
+        return 0
+
+    best_score = 0.0
+
+    for raw_a1 in raw1:
+        for raw_a2 in raw2:
+            if not raw_a1 or not raw_a2:
+                continue
+
+            # ── Extract components from both raw addresses ────────────────
+            comp1 = _extract_components(raw_a1)
+            comp2 = _extract_components(raw_a2)
+
+            hno1  = _norm(comp1.get("house_number"))
+            hno2  = _norm(comp2.get("house_number"))
+            flat1 = _norm(comp1.get("flat_number"))
+            flat2 = _norm(comp2.get("flat_number"))
+            apt1  = _norm(comp1.get("apartment"))
+            apt2  = _norm(comp2.get("apartment"))
+            str1  = _norm(comp1.get("street"))
+            str2  = _norm(comp2.get("street"))
+
+            # ── Remaining address → model input ───────────────────────────
+            rem1 = comp1.get("remaining_address", "").strip()
+            rem2 = comp2.get("remaining_address", "").strip()
+
+            # Fallback to full preprocessed address if remaining is empty
+            if not rem1:
+                rem1 = _preprocess_addr(raw_a1).upper()
+            if not rem2:
+                rem2 = _preprocess_addr(raw_a2).upper()
+
+            addr1_clean = _strip_postbox(rem1) or rem1
+            addr2_clean = _strip_postbox(rem2) or rem2
+
+            # Named components comparison (on full preprocessed address)
+            addr1_full = _preprocess_addr(raw_a1).upper()
+            addr2_full = _preprocess_addr(raw_a2).upper()
+            named_result = _compare_named(addr1_full, addr2_full)
+            pb_result    = _compare_postbox(addr1_full, addr2_full)
+
+            try:
+                base_score = float(match_entities(addr1_clean, addr2_clean,
+                                                  weights=ADDRESS_MODEL_WEIGHTS))
+            except (TypeError, ValueError):
+                base_score = 0.0
+
+            # ── Component adjustments (only when base_score > 60) ─────────
+            comp_adj = 0.0
+            component_specs = [
+                ("house_number", hno1,  hno2,  30.0, 30.0),
+                ("flat_number",  flat1, flat2, 10.0, 10.0),
+                ("apartment",    apt1,  apt2,  10.0, 10.0),
+                ("street",       str1,  str2,  10.0, 10.0),
+            ]
+            print(f"[ADDR_COMPONENTS] base_score={base_score:.2f} | threshold=60 | adjustments_applied={base_score > 60}")
+            print(f"  remaining_addr1 : {addr1_clean!r}")
+            print(f"  remaining_addr2 : {addr2_clean!r}")
+            for label, v1, v2, boost, penalty in component_specs:
+                verdict, adj = _component_adj(v1, v2, boost, penalty)
+                if verdict == "missing":
+                    print(f"  {label:<15} | verdict=missing   | v1={v1!r:>10} v2={v2!r:<10} | adjustment=0.0  [skipped - component absent]")
+                elif base_score <= 60:
+                    print(f"  {label:<15} | verdict={verdict:<9} | v1={v1!r:>10} v2={v2!r:<10} | adjustment=0.0  [SKIPPED - base_score<=60]")
+                else:
+                    comp_adj += adj
+                    sign = "+" if adj >= 0 else ""
+                    tag  = "BOOSTED" if adj > 0 else "PENALISED"
+                    print(f"  {label:<15} | verdict={verdict:<9} | v1={v1!r:>10} v2={v2!r:<10} | adjustment={sign}{adj:.1f} [{tag}]")
+            print(f"  total comp_adj  : {comp_adj:+.1f}")
+
+            adjustment = comp_adj + named_result['score_adjustment'] + pb_result['adjustment']
+            final_score = max(0.0, min(100.0, base_score + adjustment))
+            if final_score > best_score:
+                best_score = final_score
+
+    return round(best_score, 2)
+
+
+def match_addresses_structured(
+    addrs_r1: List[dict],
+    addrs_r2: List[dict],
+) -> float:
+    """
+    Match addresses when city / zipcode / state are available as separate columns.
+
+    Each address dict must have keys: addressline, city, zipcode, state.
+    Returns best score across all N×M combinations (0-100).
+
+    Handles:
+      - Missing state/city → inferred from zipcode via pgeocode (offline)
+      - Bank state codes (NDH, BLR …) → canonical form
+      - City name variants → canonical via CITY_MAPPING
+      - House number extraction + comparison
+      - Full addressline text via embedding model
+
+    Example:
+        addrs1 = [{"addressline": "A13 GUPTA ENCLAVE...",
+                   "city": "NEW DELHI", "zipcode": "110059", "state": "NDH"}]
+        addrs2 = [{"addressline": "A13 GUPTA ENCLAVE...",
+                   "city": "NEW DELHI", "zipcode": "110059", "state": "DELHI"}]
+        score = match_addresses_structured(addrs1, addrs2)  # → ~100
+    """
+    from services.rules import match_structured_address_lists as _sa_match
+    return _sa_match(addrs_r1, addrs_r2)
+
+def match_single_field(value1: str, value2: str) -> float:
+    """
+    Match single fields like SPOUSENAME, MOTHERNAME, etc.
+    Returns similarity score as float or "missing value"
+    """
+    return match_entities(value1, value2)