document-ocr 0.0.0-stage → 3.1.3

package/hosting/core/card_recovery.py

@@ -0,0 +1,244 @@
+"""Bounded pixel rereads for an identified, incomplete US passport-card front."""
+from __future__ import annotations
+
+import re
+
+import cv2
+import numpy as np
+
+from .ocr_engine import TextRegion
+from .structured_documents import _us_date, extract_structured_document
+
+_FIELD_LABELS = {
+    'document_number': re.compile(r'^(?:passport\s*(?:card[\s\'’]*)?(?:number|no\.?)|card (?:number|no\.?))(?![A-Za-z])', re.I),
+    'expiry_date': re.compile(r'^(?:card expires|expires(?:\s*on)?|date of expiry|expiration date|expiry date|EXP)(?![A-Za-z])', re.I),
+}
+
+_TRUNCATED_DATE = re.compile(r'(?:\d{1,2}\s*[A-Za-z]{3,9}\s*\d{1,3}|\d{1,2}[-/]\d{1,2}[-/]\d{1,3})')
+
+
+def _read_box(image, corners, width, height, reader) -> list[TextRegion]:
+    corners = np.asarray(corners, np.float32)
+    if (not 10 <= width <= 1600 or not 8 <= height <= 1200
+            or corners.shape != (4, 2) or not np.isfinite(corners).all()):
+        return []
+    target = np.float32([[0, 0], [width - 1, 0], [width - 1, height - 1], [0, height - 1]])
+    matrix = cv2.getPerspectiveTransform(corners, target)
+    if abs(np.linalg.det(matrix)) < 1e-12:
+        return []
+    crop = cv2.warpPerspective(image, matrix, (width, height), borderValue=(255, 255, 255))
+    inverse = np.linalg.inv(matrix)
+    result = []
+    for row in reader(crop):
+        points = np.asarray(row.bbox, np.float32)
+        if points.shape == (4, 2) and np.isfinite(points).all() and np.isfinite(row.confidence):
+            original = cv2.perspectiveTransform(points[None], inverse)[0]
+            result.append(TextRegion(row.text, original.round().astype(int).tolist(), row.confidence))
+    return result
+
+
+def _card_text_box(image, regions):
+    """Follow a confident issuer heading and nearby text with the same angle."""
+    headers = [row for row in regions if row.confidence >= .9 and len(row.bbox) == 4
+               and re.fullmatch(r'UNITED STATES(?: OF AMERICA)?', row.text.strip(), re.I)]
+    for header in sorted(headers, key=lambda row: len(row.text), reverse=True):
+        points = np.asarray(header.bbox, np.float32)
+        if not np.isfinite(points).all():
+            continue
+        origin = points[0]
+        along = points[1] - origin
+        width = np.linalg.norm(along)
+        if width < 200:
+            continue
+        along /= width
+        axes = np.array([along, [-along[1], along[0]]])
+        cluster = []
+        for row in regions:
+            points = np.asarray(row.bbox, np.float32)
+            if points.shape != (4, 2) or not np.isfinite(points).all():
+                continue
+            direction = points[1] - points[0]
+            length = np.linalg.norm(direction)
+            local = (points - origin) @ axes.T
+            if (length > 0 and direction @ along / length >= .96
+                    and local[:, 0].min() > -.15 * width and local[:, 0].max() < 1.2 * width
+                    and local[:, 1].min() > -.08 * width and local[:, 1].max() < .85 * width):
+                cluster.append(local)
+        if len(cluster) < 5:
+            continue
+        points = np.vstack(cluster)
+        left, top = points.min(axis=0) - [width * .07, width * .03]
+        right, bottom = points.max(axis=0) + [width * .07, width * .05]
+        crop_width, crop_height = int(right - left), int(bottom - top)
+        h, w = image.shape[:2]
+        if not (crop_width <= 1600 and crop_height <= 1200
+                and 0 < crop_width * crop_height < w * h * .7):
+            continue
+        corners = np.array([[left, top], [right, top], [right, bottom], [left, bottom]]) @ axes + origin
+        if (corners[:, 0].min() < 0 or corners[:, 1].min() < 0
+                or corners[:, 0].max() >= w or corners[:, 1].max() >= h):
+            continue
+        return corners, crop_width, crop_height
+    return None
+
+
+def _expiry_date_region(regions):
+    """Select one truncated date directly below one confident expiry label."""
+    labels = [row for row in regions if row.confidence >= .9
+              and _FIELD_LABELS['expiry_date'].fullmatch(row.text.strip())]
+    if len(labels) != 1:
+        return None
+    label = np.asarray(labels[0].bbox, np.float32)
+    if label.shape != (4, 2) or not np.isfinite(label).all():
+        return None
+    along = label[1] - label[0]
+    width = np.linalg.norm(along)
+    if width < 20:
+        return None
+    along /= width
+    axes = np.array([along, [-along[1], along[0]]])
+    local_label = (label - label[0]) @ axes.T
+    height = np.ptp(local_label[:, 1])
+    if height < 8:
+        return None
+    candidates = []
+    for row in regions:
+        if not _TRUNCATED_DATE.fullmatch(row.text.strip()) or _us_date(row.text) is not None:
+            continue
+        points = np.asarray(row.bbox, np.float32)
+        if points.shape != (4, 2) or not np.isfinite(points).all():
+            continue
+        direction = points[1] - points[0]
+        length = np.linalg.norm(direction)
+        local = (points - label[0]) @ axes.T
+        left, top = local.min(axis=0)
+        right, bottom = local.max(axis=0)
+        # Compare the top-edge centers. Taking the extreme corner exaggerates
+        # overlap when a long date and its short label have slightly different
+        # detected angles despite sharing the same printed baseline.
+        gap = local[:2, 1].mean() - local_label[:, 1].max()
+        if (length > 0 and direction @ along / length >= .98
+                and abs(left) <= max(20, height * 2)
+                and -.25 * height <= gap <= 2.5 * height
+                and .65 * height <= bottom - top <= 2.5 * height
+                and 0 < right - left <= width * 3):
+            candidates.append(row)
+    return candidates[0] if len(candidates) == 1 else None
+
+
+def _read_expiry_date(image, regions, recognize_line, unenhanced_image=None):
+    """At most two direct reads, with agreement required for denoise recovery."""
+    anchor = _expiry_date_region(regions)
+    if anchor is None:
+        return []
+    tl, tr, br, bl = np.asarray(anchor.bbox, np.float32)
+    along = tr - tl
+    corners = np.array([tl - .05 * along, tr + .05 * along,
+                        br + .05 * along, bl - .05 * along])
+    h, w = image.shape[:2]
+    if (corners[:, 0].min() < 0 or corners[:, 1].min() < 0
+            or corners[:, 0].max() >= w or corners[:, 1].max() >= h):
+        return []
+    width, height = int(np.linalg.norm(along) * 1.1), int(np.linalg.norm(bl - tl))
+    prefix = re.sub(r'[\s/-]', '', anchor.text).upper()
+
+    def valid(read):
+        # Preserve all characters already observed in the truncated date. The
+        # missing suffix must come from pixels and parse as a complete date.
+        return (len(read) == 1 and _us_date(read[0].text) is not None
+                and re.sub(r'[\s/-]', '', read[0].text).upper().startswith(prefix))
+
+    direct = _read_box(image, corners, width, height, recognize_line)
+    if not valid(direct):
+        # A security background can obscure the final digit after CLAHE. Keep
+        # the exact observed prefix, and reread the same coordinates once in
+        # the original-color plane. Never run both this and denoise recovery.
+        if (len(direct) == 1 and direct[0].confidence >= .9
+                and re.sub(r'[\s/-]', '', direct[0].text).upper() == prefix
+                and unenhanced_image is not None and unenhanced_image is not image
+                and unenhanced_image.shape == image.shape):
+            original = _read_box(unenhanced_image, corners, width, height, recognize_line)
+            if valid(original) and original[0].confidence >= .9:
+                return original
+        return []
+    if direct[0].confidence >= .9:
+        return direct
+    if direct[0].confidence < .8:
+        return []
+    denoised = _read_box(image, corners, width, height,
+                         lambda crop: recognize_line(cv2.medianBlur(crop, 3)))
+    if (valid(denoised) and denoised[0].confidence >= .9
+            and _us_date(denoised[0].text) == _us_date(direct[0].text)):
+        return denoised
+    return []
+
+
+def recover_card_fields(image, regions: list[TextRegion], ocr, recognize_line, *,
+                        unenhanced_image=None) -> list[TextRegion]:
+    before = extract_structured_document(regions)
+    if (before is None or before.document_type != 'passport_card' or before.issuing_country != 'US'
+            or before.complete or before.errors or len(before.fields) < 3
+            or not {'document_number', 'expiry_date'}.intersection(before.missing_required_fields)):
+        return regions
+
+    def acceptable(after):
+        return bool(after and after.complete and after.issuing_country == before.issuing_country
+                    and all(after.fields.get(key) == value for key, value in before.fields.items())
+                    and all(after.field_evidence.get(key)
+                            and min(item['confidence'] for item in after.field_evidence[key]) >= .9
+                            for key in after.fields.keys() - before.fields.keys()))
+
+    output = list(regions)
+    if before.missing_required_fields == ['expiry_date']:
+        # No detector rerun: one observed date box, at most two direct reads.
+        # Cards missing other fields keep the existing number/cluster budget.
+        date_read = _read_expiry_date(image, regions, recognize_line, unenhanced_image)
+        if date_read:
+            candidate = output + date_read
+            if acceptable(extract_structured_document(candidate)):
+                return candidate
+    if 'document_number' not in before.fields:
+        # Locate an observed card-number label fragment. The fresh pixel read
+        # must contain the exact label; its spelling is never patched in code.
+        anchor = next((row for row in regions if row.confidence >= .9 and len(row.bbox) == 4
+                       and re.fullmatch(r'.{1,24}\bcard\s+(?:number|no\.?)', row.text.strip(), re.I)
+                       and not re.match(r'passport\s*card', row.text.strip(), re.I)), None)
+        if anchor:
+            points = np.asarray(anchor.bbox, np.float32)
+            if np.isfinite(points).all():
+                tl, tr, br, bl = points
+                along = tr - tl
+                width, height = int(np.linalg.norm(along)), int(np.linalg.norm(bl - tl))
+                read = _read_box(image, [tl - .02 * along, tr + .02 * along,
+                                         br + .02 * along, bl - .02 * along], width, height, recognize_line)
+                if (len(read) == 1 and read[0].confidence >= .9
+                        and re.fullmatch(r'passport\s*card\s+(?:number|no\.?)', read[0].text.strip(), re.I)):
+                    output.extend(read)
+    current = extract_structured_document(output)
+    if current is None:
+        return regions
+    if current.complete:
+        return output if acceptable(current) else regions
+    geometry = _card_text_box(image, regions)
+    if geometry is None:
+        return regions
+    reread = _read_box(image, *geometry, ocr)
+    independently_read = extract_structured_document(reread)
+    if independently_read is None or independently_read.document_type != before.document_type or independently_read.errors:
+        return regions
+    if any(key in independently_read.fields and independently_read.fields[key] != value
+           for key, value in before.fields.items()):
+        return regions
+    # Keep unrelated reread text (especially large specimen watermarks) out of
+    # existing field association. Admit only missing labels and their values.
+    additions = []
+    for key, label in _FIELD_LABELS.items():
+        if key in current.fields or key not in independently_read.fields:
+            continue
+        evidence_boxes = [item['bbox'] for item in independently_read.field_evidence.get(key, [])]
+        additions.extend(row for row in reread if row.confidence >= .9
+                         and (label.match(row.text.strip()) or row.bbox in evidence_boxes))
+    candidate = output + additions
+    after = extract_structured_document(candidate)
+    # Every newly admitted field must have high-confidence observed evidence.
+    return candidate if acceptable(after) else regions

package/hosting/core/document_bundle.py

@@ -0,0 +1,82 @@
+"""Batch independent documents, or reconcile explicitly grouped document pages."""
+from __future__ import annotations
+
+import time
+
+from .document_input import MAX_PAGES, input_bytes, pdf_pages
+from .document_registry import validate_document_hint
+from .pipeline import scan, _scan_page, DocumentScanResult
+from .preprocessor import PreprocessResult, ImageQualityError
+
+
+def scan_batch(images, **options) -> dict:
+    if not 1 <= len(images) <= MAX_PAGES:
+        raise ValueError('INVALID_BATCH_SIZE')
+    results = [scan(data, **options).to_dict() for data in images]
+    successes = sum(r['status'] == 'success' for r in results)
+    return {'status': 'success' if successes == len(results) else 'partial' if successes else 'failure',
+            'results': results, 'errors': []}
+
+
+def scan_document(images, **options) -> dict:
+    """Merge same-family pages only; disagreements require human review.
+
+    Independent records belong in scan_batch. A conflicting field is omitted
+    from the merged fields, with all page values retained in conflicts/results.
+    """
+    if not 1 <= len(images) <= MAX_PAGES:
+        raise ValueError('INVALID_BATCH_SIZE')
+    document_type, country = validate_document_hint(options.get('document_type'), options.get('country'))
+    results = []
+    for data in images:
+        data = input_bytes(data)
+        if data.startswith(b'%PDF-'):
+            try:
+                pages = pdf_pages(data)
+                if len(results) + len(pages) > MAX_PAGES:
+                    raise ValueError('TOO_MANY_PAGES')
+                for page in pages:
+                    result = _scan_page(PreprocessResult(page.image), time.monotonic(), document_type,
+                                        country, True, native=page.regions)
+                    results.append(result.to_dict())
+            except ImageQualityError as exc:
+                results.append(DocumentScanResult('failure', 'unknown', 'unknown', 0, errors=[str(exc)]).to_dict())
+        else:
+            results.append(scan(data, document_type=document_type, country=country, include_evidence=True).to_dict())
+        if len(results) > MAX_PAGES:
+            raise ValueError('TOO_MANY_PAGES')
+    return reconcile_pages(results, include_evidence=options.get('include_evidence', False))
+
+
+def reconcile_pages(results: list[dict], *, include_evidence: bool = True) -> dict:
+    values = {}
+    for page, result in enumerate(results, 1):
+        for key, value in result.get('documentFields', {}).items():
+            if value is not None and value != '' and value != []:
+                values.setdefault(key, []).append({'page': page, 'value': value})
+        if result['documentType'] != 'unknown':
+            values.setdefault('documentType', []).append({'page': page, 'value': result['documentType']})
+        if result.get('issuingCountry'):
+            values.setdefault('issuingCountry', []).append({'page': page, 'value': result['issuingCountry']})
+        for items in result.get('fieldEvidence', {}).values():
+            for item in items:
+                item['page'] = page
+        if not include_evidence:
+            result.pop('fieldEvidence', None)
+            result.pop('imageSize', None)
+    merged, conflicts = {}, []
+    for key, entries in values.items():
+        first = entries[0]['value']
+        # Only whitespace/case differences can be merged without a domain rule.
+        def canonical(value):
+            return ' '.join(value.upper().split()) if isinstance(value, str) else value
+        if any(canonical(e['value']) != canonical(first) for e in entries):
+            conflicts.append({'field': key, 'values': entries})
+        elif key not in {'documentType', 'issuingCountry'}:
+            merged[key] = first
+    if any(conflict['field'] == 'documentType' for conflict in conflicts):
+        merged = {}
+    errors = ['CONFLICTING_DOCUMENT_PAGES'] if conflicts else []
+    successful = sum(r['status'] == 'success' for r in results)
+    status = 'failure' if conflicts else ('success' if successful == len(results) else 'partial' if successful else 'failure')
+    return {'status': status, 'results': results, 'documentFields': merged, 'conflicts': conflicts, 'errors': errors}

package/hosting/core/document_classifier.py

@@ -0,0 +1,233 @@
+"""
+Document-type router.
+
+Given OCR regions for a full document image, decides which supported document
+type it is — passport, PAN, Aadhaar, driving licence, voter ID, NREGA job card,
+or NPR letter — using a combination of keyword hints and identifier-format
+signals. The pipeline uses it as the full-page KYC router and as a conservative
+confirmation step when generic biodata labels make the cheap passport probe
+ambiguous.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .ocr_engine import TextRegion
+from .page_classifier import _has_mrz_like_lines, _normalise_text
+from .validators import (
+    extract_aadhaar_number,
+    is_valid_aadhaar,
+    normalize_dl,
+    normalize_epic,
+    normalize_pan,
+)
+
+# ---------------------------------------------------------------------------
+# Keyword hints (normalised: upper-case, alphanumerics only). Deliberately
+# avoid generic phrases like "GOVERNMENT OF INDIA" that appear on several docs.
+# ---------------------------------------------------------------------------
+
+_PAN_KEYWORDS = ["INCOME TAX DEPARTMENT", "PERMANENT ACCOUNT NUMBER", "INCOME TAX"]
+_AADHAAR_KEYWORDS = [
+    "AADHAAR", "AADHAR", "UNIQUE IDENTIFICATION", "UIDAI", "MERA AADHAAR",
+    "ENROLLMENT NO", "VID",
+]
+_DL_KEYWORDS = [
+    "DRIVING LICENCE", "DRIVING LICENSE", "TRANSPORT DEPARTMENT",
+    "MOTOR VEHICLE", "FORM 7",
+]
+_VOTER_KEYWORDS = [
+    "ELECTION COMMISSION", "ELECTORS PHOTO IDENTITY", "ELECTOR",
+    "ELECTION", "IDENTITY CARD",
+]
+_NREGA_EXPLICIT_KEYWORDS = [
+    "MAHATMA GANDHI NATIONAL RURAL EMPLOYMENT GUARANTEE ACT",
+    "MAHATMA GANDHI NATIONAL RURAL EMPLOYMENT GUARANTEE SCHEME",
+    "MAHATMA GANDHI NREGA",
+    "MGNREGA",
+]
+_NREGA_JOB_CARD_KEYWORDS = ["JOB CARD", "EMPLOYMENT CARD"]
+_NREGA_RURAL_CONTEXT = [
+    "GRAM PANCHAYAT",
+    "RURAL EMPLOYMENT",
+    "EMPLOYMENT GUARANTEE",
+    "HOUSEHOLD MEMBERS WILLING TO WORK",
+]
+_NPR_TITLE_KEYWORDS = ["NATIONAL POPULATION REGISTER"]
+_NPR_ISSUER_KEYWORDS = ["REGISTRAR GENERAL", "CENSUS COMMISSIONER"]
+_PASSPORT_KEYWORDS = ["PASSPORT", "REPUBLIC OF INDIA PASSPORT"]
+
+
+@dataclass
+class DocumentClassification:
+    document_type: str
+    confidence: float
+    reasons: list[str] = field(default_factory=list)
+    probe_text: list[str] = field(default_factory=list)
+
+
+def _count_keyword_matches(normalised_regions: list[str], keywords: list[str]) -> int:
+    matched: set[str] = set()
+    for keyword in keywords:
+        norm_kw = _normalise_text(keyword)
+        padded = f" {norm_kw} "
+        for region_text in normalised_regions:
+            if padded in f" {region_text} ":
+                matched.add(norm_kw)
+                break
+    # Treat nested phrases as one piece of evidence.  For example,
+    # ``ELECTION COMMISSION`` must not also count as an independent match for
+    # ``ELECTION`` merely because both strings occur in the same phrase.
+    independent = {
+        keyword
+        for keyword in matched
+        if not any(
+            keyword != other
+            and f" {keyword} " in f" {other} "
+            for other in matched
+        )
+    }
+    return len(independent)
+
+
+def _any_token(regions: list[TextRegion], normalizer) -> bool:
+    return any(normalizer(r.text) is not None for r in regions if r.text.strip())
+
+
+def classify_document(regions: list[TextRegion]) -> DocumentClassification:
+    """Classify a full-page document into one of the supported types."""
+    probe_text = [r.text.strip() for r in regions if r.text.strip()][:15]
+    normalised_regions = [_normalise_text(r.text) for r in regions if r.text.strip()]
+    joined_raw = " ".join(r.text for r in regions if r.text.strip())
+    joined_normalised = _normalise_text(joined_raw)
+
+    # --- per-type evidence ---
+    pan_kw = _count_keyword_matches(normalised_regions, _PAN_KEYWORDS)
+    aadhaar_kw = _count_keyword_matches(normalised_regions, _AADHAAR_KEYWORDS)
+    dl_kw = _count_keyword_matches(normalised_regions, _DL_KEYWORDS)
+    voter_kw = _count_keyword_matches(normalised_regions, _VOTER_KEYWORDS)
+    nrega_explicit_kw = _count_keyword_matches(
+        normalised_regions, _NREGA_EXPLICIT_KEYWORDS
+    )
+    nrega_explicit_kw = max(
+        nrega_explicit_kw,
+        _count_keyword_matches([joined_normalised], _NREGA_EXPLICIT_KEYWORDS),
+    )
+    nrega_job_card_kw = _count_keyword_matches(
+        normalised_regions, _NREGA_JOB_CARD_KEYWORDS
+    )
+    nrega_context_kw = _count_keyword_matches(
+        normalised_regions, _NREGA_RURAL_CONTEXT
+    )
+    npr_title_kw = _count_keyword_matches(normalised_regions, _NPR_TITLE_KEYWORDS)
+    npr_title_kw = max(
+        npr_title_kw,
+        _count_keyword_matches([joined_normalised], _NPR_TITLE_KEYWORDS),
+    )
+    npr_issuer_kw = _count_keyword_matches(normalised_regions, _NPR_ISSUER_KEYWORDS)
+    passport_kw = _count_keyword_matches(normalised_regions, _PASSPORT_KEYWORDS)
+
+    nrega_hindi_titles = (
+        "राष्ट्रीय ग्रामीण रोजगार गारंटी",
+        "महात्मा गांधी राष्ट्रीय ग्रामीण रोजगार गारंटी",
+    )
+    has_nrega_hindi_title = any(
+        title in joined_raw for title in nrega_hindi_titles
+    )
+    has_nrega_hindi_card_context = (
+        "जॉब कार्ड" in joined_raw
+        and any(
+            phrase in joined_raw
+            for phrase in ("ग्राम पंचायत", "रोजगार गारंटी")
+        )
+    )
+    has_nrega_acronym = any(
+        f" NREGA " in f" {region_text} " for region_text in normalised_regions
+    )
+    has_npr_hindi_title = (
+        "राष्ट्रीय जनसंख्या रजिस्टर" in joined_raw
+    )
+    has_npr_acronym = any(
+        f" NPR " in f" {region_text} " for region_text in normalised_regions
+    )
+
+    has_pan = _any_token(regions, normalize_pan)
+    aadhaar_number = extract_aadhaar_number(joined_raw)
+    aadhaar_checksum_ok = is_valid_aadhaar(joined_raw)
+    has_dl = _any_token(regions, normalize_dl)
+    has_epic = _any_token(regions, normalize_epic)
+    has_mrz = _has_mrz_like_lines(regions)
+
+    scores: dict[str, float] = {}
+    reasons: dict[str, list[str]] = {}
+
+    def add(doc: str, score: float, *why: str):
+        scores[doc] = scores.get(doc, 0.0) + score
+        reasons.setdefault(doc, []).extend(why)
+
+    # Keyword weight: 2 per distinct phrase. Format/identifier weight: 3.
+    if pan_kw:
+        add("pan", 2 * pan_kw, f"PAN_KEYWORDS_{pan_kw}")
+    if has_pan:
+        add("pan", 3, "PAN_FORMAT")
+
+    if aadhaar_kw:
+        add("aadhaar", 2 * aadhaar_kw, f"AADHAAR_KEYWORDS_{aadhaar_kw}")
+    if aadhaar_number:
+        add("aadhaar", 3, "AADHAAR_NUMBER")
+    if aadhaar_checksum_ok:
+        add("aadhaar", 2, "AADHAAR_CHECKSUM_VALID")
+
+    if dl_kw:
+        add("driving_licence", 2 * dl_kw, f"DL_KEYWORDS_{dl_kw}")
+    if has_dl:
+        add("driving_licence", 3, "DL_FORMAT")
+
+    if voter_kw:
+        add("voter_id", 2 * voter_kw, f"VOTER_KEYWORDS_{voter_kw}")
+    if has_epic:
+        add("voter_id", 3, "EPIC_FORMAT")
+
+    # NREGA cards do not have one public, nationally check-summed identifier
+    # shape. Require an explicit scheme title/acronym, or "Job Card" together
+    # with rural-employment context. A generic employee "job card" is not enough.
+    if nrega_explicit_kw or has_nrega_hindi_title:
+        add(
+            "nrega_job_card",
+            9 + min(nrega_explicit_kw, 2),
+            "NREGA_EXPLICIT_TITLE",
+        )
+    elif (
+        (has_nrega_acronym and (nrega_job_card_kw or nrega_context_kw))
+        or (nrega_job_card_kw and nrega_context_kw)
+        or has_nrega_hindi_card_context
+    ):
+        add("nrega_job_card", 8, "NREGA_JOB_CARD_CONTEXT")
+
+    # "NPR" is also used by unrelated organisations. Accept the acronym only
+    # alongside the issuing authority; the full English/Hindi title is strong
+    # enough by itself.
+    if npr_title_kw or has_npr_hindi_title:
+        add("npr_letter", 9, "NPR_EXPLICIT_TITLE")
+    elif has_npr_acronym and npr_issuer_kw:
+        add("npr_letter", 8, "NPR_ISSUER_CONTEXT")
+
+    if passport_kw:
+        add("passport", 2 * passport_kw, f"PASSPORT_KEYWORDS_{passport_kw}")
+    if has_mrz:
+        add("passport", 4, "MRZ_DETECTED")
+
+    if not scores:
+        return DocumentClassification("unknown", 0.2, ["NO_DOCUMENT_HINTS"], probe_text)
+
+    best_doc = max(scores, key=lambda d: scores[d])
+    best_score = scores[best_doc]
+
+    confidence = round(min(0.5 + 0.12 * best_score, 0.98), 3)
+    return DocumentClassification(
+        document_type=best_doc,
+        confidence=confidence,
+        reasons=reasons.get(best_doc, []),
+        probe_text=probe_text,
+    )