document-ocr 0.0.0-stage → 3.1.3

package/hosting/README.md

@@ -0,0 +1,369 @@
+# document-ocr
+
+Local-first OCR pipeline for passports, Indian KYC documents, and experimental US identity/immigration/tax documents. It
+preprocesses scans, classifies the document, runs targeted OCR with RapidOCR
+(PP-OCRv5), and extracts structured fields—including passport MRZ data, Indian
+passport back-page fields, and identifier/holder fields for PAN, Aadhaar,
+driving licences, voter IDs, MGNREGA/NREGA job cards, and National Population
+Register (NPR) name-and-address letters.
+
+Ships as a Python package with a FastAPI server, plus an npm wrapper at [`packages/passport-ocr`](packages/passport-ocr) that auto-spawns the Python server for Node.js consumers.
+
+> [!IMPORTANT]
+> This project is beta software for data extraction. It does not establish
+> document authenticity, verify identity against an issuing authority, detect
+> fraud, or by itself satisfy KYC obligations. Evaluate it on your own legally
+> obtained dataset before production use.
+
+Version 3.1 adds US document profiles, PDF417/TD1/visa parsing, country hints,
+field evidence, native PDF text, grouped pages, batch scans, a browser review UI,
+redaction, and optional encrypted jobs. See [FEATURES.md](FEATURES.md) for the
+contracts and coverage limits and [HOSTING.md](HOSTING.md) for Cloud Run, Lambda,
+Cloudflare Containers, servers, Terraform, and the deployment CLI.
+
+## Supported documents
+
+| Document | Key fields extracted | Identifier validation |
+|---|---|---|
+| Passport (biodata) | name, passport no., nationality, DOB, sex, expiry/issue dates, place of birth | TD3 MRZ ICAO check digits |
+| Passport (back page) | father/mother/spouse, address, file no., old passport details | — |
+| PAN card | PAN, name, father's name, DOB | PAN format + holder-type char |
+| Aadhaar (front/back) | Aadhaar no. (+ VID, masked-card support), name, DOB/YOB, gender, address, pincode | Verhoeff checksum |
+| Driving licence | DL no., name, DOB, issue/validity dates (NT + TR), address, blood group, vehicle class | DL format |
+| Voter ID (EPIC) | EPIC no., name, relation name + type, gender, DOB/age | EPIC format |
+| MGNREGA/NREGA job card | job-card no., household head, registration/validity, location, category/BPL, adult members | Conservative hierarchical format |
+| NPR name/address letter | reference no., resident name, address, pincode, issue date | Not offline-verifiable |
+
+Together with the existing passport path, this covers the officially valid
+document categories listed in the
+[RBI KYC Master Direction](https://www.rbi.org.in/Scripts/BS_ViewMasDirections.aspx?id=11566);
+PAN is supported as a separate tax identifier.
+
+The document type is detected automatically; `/scan` returns the matching
+field block (`fields`/`backPageFields` for passports, or `panFields`,
+`aadhaarFields`, `drivingLicenceFields`, `voterIdFields`,
+`nregaJobCardFields`, or `nprLetterFields`) keyed by `documentType`.
+
+NREGA and NPR support is experimental until measured against a representative
+private image dataset. The extraction layer handles multiple label/layout
+variants, but deterministic text-region tests are not evidence of real-image
+accuracy.
+
+Country/document hints route through full-page classification rather than relying
+on an ambiguous passport crop. New structured-document evidence can also override
+generic passport-like labels. Unknown or conflicting document hints fail explicitly.
+
+## Quickstart
+
+### Python
+
+Requires Python 3.14 and [`uv`](https://github.com/astral-sh/uv).
+
+```bash
+make install
+make dev          # uvicorn on :8000 with reload
+```
+
+Scan a document:
+
+```bash
+curl -F image=@/path/to/document.jpg \
+  http://localhost:8000/scan
+```
+
+### Docker
+
+```bash
+make docker-build
+docker run --rm -p 8000:8000 passport-ocr
+```
+
+The image pre-downloads PP-OCRv5 models at build time so the first request is fast.
+
+### Node.js (npm package)
+
+Development and publishing use Node.js 26.12.1. The SDK retains its Node.js 18
+or later runtime requirement.
+
+```bash
+npm install document-ocr
+```
+
+When npm blocks dependency install scripts, approve this package and finish its
+local Python setup:
+
+```bash
+npm install-scripts approve document-ocr
+npm rebuild document-ocr
+```
+
+```ts
+import { DocumentOCR } from 'document-ocr';
+
+const ocr = new DocumentOCR();
+const result = await ocr.scan(imageBuffer);
+
+if (result.status === 'success' && result.documentType === 'passport') {
+  console.log(result.fields.passportNumber, result.mrzValid);
+}
+await ocr.stop();
+```
+
+The package auto-creates a `.venv`, installs the Python deps, and manages the local server lifecycle. See [`packages/passport-ocr/README.md`](packages/passport-ocr/README.md) for full options including HTTP mode.
+
+## HTTP API
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/health` | Liveness |
+| GET | `/ready` | `503` until OCR models finish loading |
+| GET | `/documents` | Document profiles and runtime capabilities |
+| POST | `/scan` | Single scan with country/document hints and optional evidence |
+| POST | `/scan/batch` | Independent inputs, preserving order |
+| POST | `/scan/document` | Grouped front/back images or all PDF pages, with conflict detection |
+| GET | `/review` | Browser review, corrections and export |
+| POST | `/preview`, `/redact` | Normalized preview or selected raster redactions |
+| POST | `/jobs` | Optional persistent-server queue |
+| GET / DELETE | `/jobs/{id}` | Poll or delete a retained job |
+
+`/scan` accepts images and PDFs up to 10 MB. Concurrency is serialized
+internally. Set `API_TOKEN` to require
+`Authorization: Bearer <token>` on document and job endpoints. For internet-facing deployments,
+use platform IAM or an API gateway in addition to application-level controls.
+Incomplete or semantically invalid non-passport extractions return HTTP `422`
+with the full structured failure result.
+
+## Output
+
+```jsonc
+{
+  "status": "success",                  // success | failure | unsupported_page
+  "documentType": "passport",           // passport | pan | aadhaar | driving_licence | voter_id | nrega_job_card | npr_letter | unknown
+  "pageType": "passport_biodata",       // same document values, plus passport_biodata | passport_non_biodata | unknown
+  "confidence": 0.91,
+  "fields": {
+    "surname": "...", "givenNames": "...", "fullName": "...",
+    "passportNumber": "...", "nationality": "IND",
+    "dateOfBirth": "1990-05-21", "sex": "M",
+    "expiryDate": "2030-04-12", "issueDate": "2020-04-13",
+    "placeOfBirth": "...", "countryCode": "IND"
+  },
+  "backPageFields": {
+    "fatherName": "...", "motherName": "...", "spouseName": "...",
+    "address": "...", "pincode": "...", "city": "...", "state": "...",
+    "fileNumber": "...", "oldPassportNumber": "...",
+    "oldPassportDateOfIssue": "...", "oldPassportPlaceOfIssue": "..."
+  },
+  // Exactly one document block is populated, keyed by documentType; the rest
+  // are null. (passport uses fields/backPageFields above.)
+  "panFields":            { "panNumber": "...", "name": "...", "fatherName": "...", "dateOfBirth": "..." },
+  "aadhaarFields":        { "aadhaarNumber": "...", "name": "...", "dateOfBirth": "...", "yearOfBirth": null,
+                            "gender": "...", "address": "...", "pincode": "...", "checksumValid": true,
+                            "aadhaarMasked": false, "aadhaarLast4": "...", "vid": null },
+  "drivingLicenceFields": { "dlNumber": "...", "name": "...", "dateOfBirth": "...", "issueDate": "...",
+                            "validityDate": "...", "address": "...", "relationName": "...", "bloodGroup": "...",
+                            "classOfVehicle": "...", "validityDateTransport": null },
+  "voterIdFields":        { "epicNumber": "...", "name": "...", "relationName": "...", "relationType": "father",
+                            "gender": "...", "dateOfBirth": "...", "age": null },
+  "nregaJobCardFields":   { "jobCardNumber": "...", "headOfHousehold": "...", "category": "SC",
+                            "registrationDate": "...", "validityFrom": "...", "validityTo": "...",
+                            "address": "...", "village": "...", "gramPanchayat": "...", "block": "...",
+                            "district": "...", "state": "...", "bplStatus": true, "familyId": "...",
+                            "members": [{ "serialNumber": "1", "name": "...",
+                                          "fatherOrHusbandName": "...", "gender": "FEMALE", "age": 39 }] },
+  "nprLetterFields":      { "referenceNumber": "...", "name": "...", "address": "...",
+                            "pincode": "...", "issueDate": "..." },
+  "mrzRaw": ["P<IND...", "..."], "mrzValid": true,
+  "lowConfidence": false,
+  "identifierValid": null,              // format/checksum only; never an authenticity verdict
+  "missingRequiredFields": [],
+  "errors": [], "warnings": [],
+  "processingMs": 412
+}
+```
+
+## Pipeline
+
+1. `preprocess` — orientation, document boundary detection, perspective correction, quality checks
+2. `classify_passport_page` — biodata vs non-biodata vs not-a-passport (cheap bottom-crop probe)
+3. passport path: `run_ocr` (RapidOCR PP-OCRv5, full-page enrichment and visual cross-checks even when the cropped MRZ is valid) → `parse_mrz` (TD3 MRZ with per-field + overall checksum validation) → `extract_back_page` (bilingual label-aware extraction) → `validate` (cross-checks MRZ vs visual fields, computes confidence)
+4. non-passport path: `classify_document` routes full-page OCR to the matching
+   extractor (`pan` / `aadhaar` / `driving_licence` / `voter_id` /
+   `nrega_job_card` / `npr_letter`), checks minimum required fields, validates
+   identifiers where possible, and fails closed on partial or semantically
+   implausible records
+
+For non-passport documents, `status: "success"` means the extractor returned
+the document-specific minimum field set and passed a conservative OCR-region
+confidence gate. Alternate model readings for the same detected geometry count
+once. `identifierValid` means only an offline format/checksum check passed. NPR
+references have no universal public checksum, so this value is `null`; it is
+never evidence of authenticity.
+
+### Non-passport OCR languages
+
+The default recognition behavior is unchanged (`en`, with the existing
+automatic fallback). If the expected KYC population uses a known script, run
+up to four recognition passes only on the non-passport path:
+
+```bash
+DOCUMENT_OCR_KYC_LANGS=en,devanagari make dev
+```
+
+Available values are `en`, `latin`, `devanagari`, `ka` (Kannada), `ta`
+(Tamil), and `te` (Telugu). Extra models increase latency and memory. The
+bundled RapidOCR version has no Bengali recognition model: Bengali-labelled
+extractor fixtures prove parsing behavior only, not Bengali image OCR. Select
+languages and release thresholds from measured benchmark slices. Server
+readiness initializes every configured model so model-download or startup
+failures are reported before the first scan. Unsupported names or more than
+four configured models fail readiness instead of silently falling back.
+
+Single entry point: `core.pipeline.scan(image_input)`.
+
+### Verification
+
+Run `make test` for Python and SDK regressions. Use `make benchmark-public` and
+`make benchmark-http` with the downloaded samples below for actual OCR accuracy
+and API verification. Locally generated smoke fixtures are not used for the
+active evaluation.
+
+Use `make benchmark` with a private passport manifest following
+[`benchmarks/PASSPORT_DATASET.md`](benchmarks/PASSPORT_DATASET.md), or
+`make benchmark-kyc KYC_MANIFEST=/secure/path/manifest.json` following
+[`benchmarks/KYC_DATASET.md`](benchmarks/KYC_DATASET.md), to measure actual image
+accuracy. Missing required coverage fails the release gates.
+
+See [`AUDIT.md`](AUDIT.md) for historical implementation review. Current accuracy
+claims use the [dataset-only evaluation](benchmarks/ALL_DOCUMENTS_EVALUATION.md).
+
+## Deployment
+
+The same pipeline runs as a container, on Cloud Run, or on AWS Lambda. Copy
+`.env.deploy.example` to `.env.deploy.<env>` and fill in the relevant values
+first (Docker Hub and/or GCP).
+
+Cloud Run and Lambda deployments are authenticated by default. Do not expose
+an identity-document endpoint publicly without authentication, authorization,
+rate limiting, encrypted transport, and an explicit data-retention policy.
+
+### Cloud Run (recommended)
+
+```bash
+# Build deploy/docker/Dockerfile, push to Artifact Registry, deploy the service.
+bash deploy/cloudrun/deploy.sh production
+# or via Cloud Build:
+gcloud builds submit --config deploy/cloudrun/cloudbuild.yaml \
+  --substitutions=_REGION=asia-south1,_SERVICE=document-ocr
+```
+
+Service config is generated by [`deploy/cloudrun/render_service.py`](deploy/cloudrun/render_service.py)
+(2 GiB / 2 vCPU, `containerConcurrency: 1` since OCR is serialized). The `economy`
+profile scales to zero; `DOCUMENT_OCR_PROFILE=warm` keeps one instance ready to
+reduce cold starts. See [hosting profiles](HOSTING.md) for deployment settings.
+
+### AWS Lambda (container image)
+
+The SDK's `mode: 'lambda'` invokes a function that takes `{ "image_base64": "..." }`.
+
+```bash
+cd deploy/lambda
+sam build && sam deploy --guided   # uses Dockerfile.lambda + template.yaml
+```
+
+The handler ([`deploy/lambda/handler.py`](deploy/lambda/handler.py)) returns the
+raw scan result on success and an `{statusCode, body}` envelope for errors.
+The included SAM template supports IAM-authenticated direct invocation and does
+not create a public API Gateway endpoint.
+
+## Tests & benchmarks
+
+```bash
+make test
+make build
+```
+
+The per-document extractors are covered by deterministic `TextRegion` fixtures
+under `tests/python/test_*_extractor.py`. These tests verify parsing and
+validation behavior; they are not a claim of real-world OCR accuracy.
+
+For the legacy passport image benchmark, place its private dataset and
+`manifest.json` under `benchmark-data/` and run:
+
+```bash
+make benchmark
+```
+
+For a non-passport KYC dataset, use the versioned manifest and release gates:
+
+```bash
+make benchmark-kyc \
+  KYC_MANIFEST=/secure/kyc-eval/manifest.json \
+  KYC_DATASET_ROOT=/secure/kyc-eval \
+  KYC_REPORT=/secure/kyc-eval/reports/main.json
+```
+
+The KYC evaluator reports classification, acceptance/false-success,
+exact/normalized field, complete-record, runtime, per-document, and
+design/year/issuer/language/capture-quality slice metrics without copying
+ground-truth values into its report. Required per-document slices fail manifest
+validation when a declared variant is absent. See
+[`benchmarks/KYC_DATASET.md`](benchmarks/KYC_DATASET.md) for the variant matrix
+and annotation workflow.
+
+`benchmark-data/` is ignored by Git. Never commit identity documents or
+personal data. See [CONTRIBUTING.md](CONTRIBUTING.md) for fixture rules.
+
+Accuracy evaluation uses **downloaded dataset documents only**. See the
+[dataset evaluation report](benchmarks/ALL_DOCUMENTS_EVALUATION.md) for matched
+accuracy, latency, API results and remaining failures.
+
+The current sample has 62 images: 39 labelled positives across non-Indian
+passport books, South Dakota licences, US passport-card fronts and W-9 forms,
+seven negative controls, and 16 observations without field truth. Some source
+datasets contain publisher-created synthetic/specimen documents; these are
+identified in the [coverage map](benchmarks/DOCUMENT_DATASET_COVERAGE.md).
+They are externally supplied images and labels, not project-generated fixtures.
+
+```bash
+.venv/bin/python -m benchmarks.public_data fetch-samples
+.venv/bin/python -m benchmarks.public_data fetch-samples --manifest benchmarks/public_expansion_samples.json
+.venv/bin/python -m benchmarks.multidoc_accuracy --output benchmark-data/public/current.json
+.venv/bin/python -m benchmarks.http_accuracy --output benchmark-data/http/current.json
+```
+
+The [real HTTP evaluator](benchmarks/HTTP_EVALUATION.md) submits those same images
+through the production server at one, two and four clients, checks PNG/JPEG/
+image-only PDF inputs and hint/evidence options, and exercises batch, grouped
+pages and queued jobs. Format conversions and repetitions do not add independent
+people. Local HTTP timing is not a deployed-worker or serverless latency guarantee.
+
+[Core CI](.github/workflows/ocr-evaluation.yml) and
+[public HTTP CI](.github/workflows/ocr-http-public.yml) compare the same downloaded
+samples, scorer, model files and environment across revisions. Correctness and
+latency are separate gates; a regression pass can still have unmet absolute
+targets. Locally generated image contracts and the agent-transcribed EAD specimen
+are excluded from automatic accuracy evaluation and its headline results.
+
+The [public dataset catalog](benchmarks/PUBLIC_DATASETS.md) and
+[additional source review](benchmarks/ADDITIONAL_SOURCE_REVIEW.md) retain links
+without downloading whole datasets. The bounded fetcher downloads only selected
+images and labels with pinned checksums. **Only four supported profiles currently
+have labelled dataset coverage. Real Indian passport and full Indian KYC accuracy
+remain unmeasured.** Missing dataset samples remain explicit coverage gaps.
+[Historical OCR results](benchmarks/PUBLIC_BASELINE.md) and
+[passport recovery comparisons](benchmarks/MRZ_RECOVERY_FOLLOWUP.md) remain available.
+
+## Privacy and security
+
+Local Python and npm-local modes process documents on the same machine and do
+not include telemetry or document storage. HTTP and Lambda modes transmit
+documents to infrastructure controlled by the operator.
+
+Read [PRIVACY.md](PRIVACY.md) before deploying and report vulnerabilities using
+[SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE). Dependencies retain their own licenses; see
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/hosting/core/aadhaar_extractor.py

@@ -0,0 +1,298 @@
+"""
+Extractor for Indian Aadhaar cards (front and back).
+
+Front fields: Aadhaar number, name, date/year of birth, gender.
+Back fields:  address, pincode.
+
+Aadhaar has no Latin field labels for the name (it sits above the DOB line), so
+the name is found spatially relative to the DOB/gender block. The Aadhaar number
+and its Verhoeff checksum are handled in core.validators.
+
+Robustness notes:
+  * VID (a 16-digit Virtual ID, grouped 4-4-4-4) is masked out of the text
+    before the 12-digit Aadhaar is extracted, otherwise the VID's first twelve
+    digits would be mis-captured as the Aadhaar number.
+  * Masked Aadhaar ("XXXX XXXX 9012") is recognised: the visible tail is
+    surfaced via ``aadhaar_masked`` / ``aadhaar_last4`` and ``checksum_valid``
+    stays False (we never crash on a missing/partial number).
+  * Gender is normalised across English and Hindi (Devanagari) spellings.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from .ocr_engine import TextRegion
+from .validator import find_label_value, find_visual_field
+from .validators import extract_aadhaar_number, is_valid_aadhaar
+
+_DATE_RE = re.compile(r"\b(\d{1,2}[/.\-]\d{1,2}[/.\-]\d{4})\b")
+_YEAR_RE = re.compile(r"\b(19\d{2}|20\d{2})\b")
+_PINCODE_RE = re.compile(r"\b(\d{6})\b")
+
+# A Virtual ID is 16 digits, printed grouped 4-4-4-4 (optionally spaced) — or as
+# a bare 16-digit run. Either form must be removed before Aadhaar extraction.
+_VID_RE = re.compile(r"\b\d{4}\s?\d{4}\s?\d{4}\s?\d{4}\b")
+_VID_LABEL_RE = re.compile(r"\bVID\b", re.IGNORECASE)
+
+# Masked Aadhaar: leading groups are X'd out and only the final 4 digits show,
+# e.g. "XXXX XXXX 9012" / "xxxxxxxx9012" / "**** **** 9012".
+_MASKED_AADHAAR_RE = re.compile(
+    r"(?:[Xx*]{4}[\s-]?){2}(\d{4})\b"
+)
+
+_GENDER_WORDS = {
+    "MALE": "MALE",
+    "FEMALE": "FEMALE",
+    "TRANSGENDER": "TRANSGENDER",
+}
+
+# Hindi (Devanagari) gender words map to the same canonical values.
+_GENDER_HINDI = {
+    "पुरुष": "MALE",
+    "महिला": "FEMALE",
+    "स्त्री": "FEMALE",
+    "किन्नर": "TRANSGENDER",
+    "ट्रांसजेंडर": "TRANSGENDER",
+}
+
+# Header / label noise that must never be mistaken for the holder name.
+_NAME_STOPWORDS = {
+    "GOVERNMENT", "GOVT", "INDIA", "BHARAT", "AADHAAR", "AADHAR", "UNIQUE",
+    "IDENTIFICATION", "AUTHORITY", "UIDAI", "MALE", "FEMALE", "TRANSGENDER",
+    "DOB", "YEAR", "BIRTH", "YOB", "ADDRESS", "MOBILE", "VID", "ENROLLMENT",
+    "ENROLMENT", "GENDER", "DATE", "NUMBER", "CARD", "DOWNLOAD", "ISSUE",
+    "ISSUED", "HELP", "EMAIL", "WWW", "PHONE", "MERA", "AADHAR", "VALID",
+}
+
+# Care-of prefixes that introduce the address on the back.
+_CARE_OF_RE = re.compile(r"\b([SCDWscdw])\s*/\s*[Oo]\b")
+
+
+@dataclass
+class AadhaarFields:
+    aadhaar_number: Optional[str] = None
+    name: Optional[str] = None
+    date_of_birth: Optional[str] = None
+    year_of_birth: Optional[str] = None
+    gender: Optional[str] = None
+    address: Optional[str] = None
+    pincode: Optional[str] = None
+    checksum_valid: bool = False
+    # --- additive fields (do not rename existing ones) ---
+    aadhaar_masked: bool = False
+    aadhaar_last4: Optional[str] = None
+    vid: Optional[str] = None
+
+
+def _devanagari_ratio(text: str) -> float:
+    """Fraction of alphabetic characters that fall in the Devanagari block."""
+    letters = [c for c in text if c.isalpha()]
+    if not letters:
+        return 0.0
+    devanagari = sum(1 for c in letters if "ऀ" <= c <= "ॿ")
+    return devanagari / len(letters)
+
+
+def _is_name_like(text: str) -> bool:
+    stripped = text.strip()
+    if len(stripped) < 3 or any(ch.isdigit() for ch in stripped):
+        return False
+    letters = [c for c in stripped if c.isalpha()]
+    if not letters:
+        return False
+    # Mostly Latin letters (Aadhaar prints the name in English too).
+    if _devanagari_ratio(stripped) > 0.5:
+        return False
+    if sum(1 for c in letters if ord(c) > 127) / len(letters) > 0.5:
+        return False
+    # A care-of address line ("S/O ...") is not the holder name.
+    if _CARE_OF_RE.search(stripped):
+        return False
+    words = re.sub(r"[^A-Z ]", " ", stripped.upper()).split()
+    if not words:
+        return False
+    return not any(w in _NAME_STOPWORDS for w in words)
+
+
+def _find_gender(regions: list[TextRegion]) -> Optional[str]:
+    for region in regions:
+        text = region.text
+        # English / Latin gender words, matched as whole words.
+        upper = re.sub(r"[^A-Z]", " ", text.upper())
+        padded = f" {upper} "
+        for word, value in _GENDER_WORDS.items():
+            if f" {word} " in padded:
+                return value
+        # Hindi (Devanagari) gender words.
+        for word, value in _GENDER_HINDI.items():
+            if word in text:
+                return value
+    return None
+
+
+def _find_dob_region(regions: list[TextRegion]) -> Optional[TextRegion]:
+    """Locate the region carrying the date/year of birth.
+
+    Prefer a region that both mentions a DOB/birth label *and* carries a date;
+    fall back to any birth-labelled region, then to any bare date region.
+    """
+    labelled_with_date: Optional[TextRegion] = None
+    labelled: Optional[TextRegion] = None
+    bare_date: Optional[TextRegion] = None
+
+    for region in regions:
+        upper = region.text.upper()
+        has_birth_label = (
+            "DOB" in upper
+            or "YEAR OF BIRTH" in upper
+            or "YOB" in upper
+            or "BIRTH" in upper
+            or "जन्म" in region.text  # Hindi "janm" (birth)
+        )
+        has_date = bool(_DATE_RE.search(region.text))
+        if has_birth_label and has_date and labelled_with_date is None:
+            labelled_with_date = region
+        elif has_birth_label and labelled is None:
+            labelled = region
+        elif has_date and bare_date is None:
+            bare_date = region
+
+    return labelled_with_date or labelled or bare_date
+
+
+def _find_name(
+    regions: list[TextRegion],
+    dob_region: Optional[TextRegion],
+    *,
+    is_front: bool,
+) -> Optional[str]:
+    candidates = [r for r in regions if _is_name_like(r.text)]
+    if not candidates:
+        return None
+    if dob_region is not None:
+        dob_top = min(p[1] for p in dob_region.bbox)
+        dob_left = min(p[0] for p in dob_region.bbox)
+        above = [r for r in candidates if max(p[1] for p in r.bbox) <= dob_top + 5]
+        if above:
+            # Closest line above the DOB, breaking ties by horizontal proximity.
+            above.sort(
+                key=lambda r: (
+                    dob_top - max(p[1] for p in r.bbox),
+                    abs(min(p[0] for p in r.bbox) - dob_left),
+                )
+            )
+            return above[0].text.strip()
+    # No DOB anchor: only guess a name on a front page (a back/address page has
+    # no holder name, and address/locality lines must not be fabricated as one).
+    if not is_front:
+        return None
+    # Fall back to the topmost name-like line (the "Government of India" band is
+    # already filtered out by the stopword list).
+    candidates.sort(key=lambda r: min(p[1] for p in r.bbox))
+    return candidates[0].text.strip()
+
+
+def _find_address(regions: list[TextRegion]) -> Optional[str]:
+    label = find_visual_field(regions, ["ADDRESS", "पता"])
+    if label is None:
+        return None
+    label_bottom = max(p[1] for p in label.bbox)
+    label_top = min(p[1] for p in label.bbox)
+    lines = []
+    for region in regions:
+        if region is label:
+            continue
+        top = min(p[1] for p in region.bbox)
+        bottom = max(p[1] for p in region.bbox)
+        # Keep lines that begin at/below the label and within a reasonable span.
+        # Also allow a line that shares the label's row (inline "Address: ...").
+        on_label_row = bottom > label_top and top < label_bottom
+        if not on_label_row and (top < label_bottom - 10 or top - label_bottom > 300):
+            continue
+        text = region.text.strip()
+        if _devanagari_ratio(text) > 0.5:
+            continue  # skip mostly-Devanagari noise lines
+        # Skip a standalone Aadhaar/VID number line printed below the address.
+        if not any(c.isalpha() for c in text) and sum(c.isdigit() for c in text) >= 8:
+            continue
+        if len(text) >= 2:
+            lines.append((top, text))
+    lines.sort(key=lambda x: x[0])
+    if not lines:
+        # Address may be on the same line as the label ("Address: ...").
+        inline = find_label_value(regions, ["ADDRESS"])
+        return inline
+    return ", ".join(text for _, text in lines[:6])
+
+
+def _strip_vid(text: str) -> tuple[str, Optional[str]]:
+    """Remove 16-digit VID sequences from ``text`` and return (cleaned, vid).
+
+    Both spaced ("9148 6541 8231 2156") and bare ("9148654182312156") 16-digit
+    forms are stripped so the downstream 12-digit Aadhaar matcher cannot slice
+    the VID's leading twelve digits. The first VID found is surfaced.
+    """
+    found: Optional[str] = None
+
+    def _replace(match: re.Match[str]) -> str:
+        nonlocal found
+        if found is None:
+            digits = re.sub(r"\D", "", match.group(0))
+            found = f"{digits[0:4]} {digits[4:8]} {digits[8:12]} {digits[12:16]}"
+        return " "
+
+    cleaned = _VID_RE.sub(_replace, text)
+    return cleaned, found
+
+
+def extract_aadhaar(regions: list[TextRegion]) -> AadhaarFields:
+    fields = AadhaarFields()
+    joined = " ".join(r.text for r in regions if r.text.strip())
+
+    # Strip any 16-digit VID first so it can't be misread as the Aadhaar number.
+    cleaned, fields.vid = _strip_vid(joined)
+
+    fields.aadhaar_number = extract_aadhaar_number(cleaned)
+    fields.checksum_valid = is_valid_aadhaar(cleaned)
+
+    # Masked Aadhaar handling: when no full number is present but a masked form
+    # ("XXXX XXXX 9012") is, surface the visible tail without claiming validity.
+    if fields.aadhaar_number is None:
+        masked = _MASKED_AADHAAR_RE.search(cleaned)
+        if masked:
+            fields.aadhaar_masked = True
+            fields.aadhaar_last4 = masked.group(1)
+    elif fields.aadhaar_number:
+        fields.aadhaar_last4 = fields.aadhaar_number.split()[-1]
+
+    fields.gender = _find_gender(regions)
+
+    dob_region = _find_dob_region(regions)
+    if dob_region is not None:
+        date_match = _DATE_RE.search(dob_region.text)
+        if date_match:
+            fields.date_of_birth = date_match.group(1)
+        else:
+            year_match = _YEAR_RE.search(dob_region.text)
+            if year_match:
+                fields.year_of_birth = year_match.group(1)
+
+    # A page is "front-like" when it carries a DOB/year or a gender word, and is
+    # not an address (back) page. The name heuristic only fabricates a fallback
+    # name on front-like pages.
+    has_address_label = find_visual_field(regions, ["ADDRESS", "पता"]) is not None
+    is_front = (
+        dob_region is not None or fields.gender is not None
+    ) and not has_address_label
+    fields.name = _find_name(regions, dob_region, is_front=is_front)
+
+    address = _find_address(regions)
+    if address:
+        fields.address = address
+        pincode = _PINCODE_RE.search(address)
+        fields.pincode = pincode.group(1) if pincode else None
+
+    return fields