document-ocr 0.0.0-stage → 3.1.3

package/python/core/structured_documents.py

@@ -0,0 +1,422 @@
+"""Country-aware extraction for explicitly registered document profiles.
+
+Machine-readable data and visual OCR remain separate evidence. Conflicting
+values are surfaced instead of silently letting a confident source overwrite
+another. These extraction checks do not authenticate a document or its holder.
+"""
+
+from __future__ import annotations
+
+import re
+import math
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Callable
+
+import pycountry
+
+from .barcodes import BarcodeResult, parse_aamva
+from .document_registry import DOCUMENT_PROFILES, normalize_country, validate_document_hint
+from .ocr_engine import TextRegion
+from .travel_mrz import parse_travel_mrz
+
+
+@dataclass
+class StructuredExtraction:
+    document_type: str
+    issuing_country: str | None = None
+    issuing_region: str | None = None
+    fields: dict = field(default_factory=dict)
+    field_evidence: dict = field(default_factory=dict)
+    checks: dict = field(default_factory=dict)
+    missing_required_fields: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    confidence: float = 0.0
+
+    @property
+    def complete(self) -> bool:
+        return bool(self.fields) and not self.missing_required_fields and not self.errors
+
+
+_US_STATES = {item.code.split("-")[1]: item.name.upper() for item in pycountry.subdivisions.get(country_code="US")}
+_FIELD_LABEL = re.compile(
+    r"^(?:\d{1,2}[a-z]?\s+)?(?:3[ab]\b|surname|family name|given names?|first name|middle name|date of birth|birth date|dob|"
+    r"date of (?:issue|expiry)|expires(?:\s*on)?|exp(?:iry|iration)?(?: date)?|iss|issue(?:d| date)?|sex|nationality|"
+    r"uscis|card (?:number|expires)|category|country of birth|resident since|valid from|"
+    r"class of admission|admit until|admission.*record number|passport number|"
+    r"name(?: of entity/individual)?|business name|address|city|social security number|employer identification number)\b",
+    re.I,
+)
+
+
+def _compact(value: str) -> str:
+    return re.sub(r"[\s-]", "", value.upper())
+
+
+def _us_date(value: str) -> str | None:
+    value = value.strip().replace(".", "/")
+    if re.fullmatch(r"[0-9\s/-]+", value):
+        value = re.sub(r"\s+", "", value)
+    # OCR often joins a printed month to its neighbouring day or year.
+    value = re.sub(r"(?<=[A-Za-z])(?=[0-9])|(?<=[0-9])(?=[A-Za-z])", " ", value)
+    for fmt in ("%m/%d/%Y", "%m-%d-%Y", "%Y-%m-%d", "%m%d%Y", "%d %b %Y", "%d %B %Y", "%d-%b-%Y",
+                "%m/%d/%y", "%m-%d-%y", "%Y %B %d", "%Y %b %d"):
+        try:
+            return datetime.strptime(value, fmt).date().isoformat()
+        except ValueError:
+            continue
+    return None
+
+
+def _name(value: str) -> str | None:
+    value = " ".join(value.strip(" :").split())
+    if not 1 <= len(value) <= 100 or not re.search(r"[A-Za-z]", value):
+        return None
+    if re.search(r"\b(?:required|enter|instructions|certification|requester|taxpayer|identification|security)\b|shown on|line [0-9]", value, re.I):
+        return None
+    return value
+
+
+def _person_name(value: str) -> str | None:
+    return _name(value) if not re.search(r"[0-9]", value) else None
+
+
+def _pattern(pattern: str) -> Callable[[str], str | None]:
+    return lambda value: _compact(value) if re.fullmatch(pattern, _compact(value)) else None
+
+
+def _document_number(value: str) -> str | None:
+    value = _compact(value)
+    return value if re.fullmatch(r"[A-Z0-9]{4,25}", value) and re.search(r"[0-9]", value) else None
+
+
+def _country_of_birth(value: str) -> str | None:
+    try:
+        return pycountry.countries.lookup(value.strip()).alpha_3
+    except LookupError:
+        return None
+
+
+def _evidence(region: TextRegion, text: str | None = None) -> dict:
+    return {"text": text if text is not None else region.text, "bbox": region.bbox, "source": "ocr", "confidence": region.confidence}
+
+
+def _label_values(regions: list[TextRegion], labels: tuple[str, ...]):
+    """Yield explicit inline values, then spatially adjacent non-label regions."""
+    for label in labels:
+        expression = re.compile(r"^\s*(?:[0-9]{1,2}[a-z]?\s+)?(?:" + label + r")(?![A-Za-z])\s*[:#]?\s*", re.I)
+        for region in regions:
+            match = expression.match(region.text)
+            if not match:
+                continue
+            inline = region.text[match.end():].strip()
+            if inline:
+                yield inline, region
+            if not region.bbox:
+                continue
+            origin, end = region.bbox[:2]
+            dx, dy = end[0] - origin[0], end[1] - origin[1]
+            length = math.hypot(dx, dy)
+            if length < 1:
+                continue
+            ux, uy = dx / length, dy / length
+
+            def bounds(other):
+                xs = [(p[0] - origin[0]) * ux + (p[1] - origin[1]) * uy for p in other.bbox]
+                ys = [-(p[0] - origin[0]) * uy + (p[1] - origin[1]) * ux for p in other.bbox]
+                return min(xs), min(ys), max(xs), max(ys)
+
+            # Match fields in the label's own axes, including tilted photos.
+            left, top, right, bottom = bounds(region)
+            height = max(bottom - top, 1)
+            nearby = []
+            for candidate in regions:
+                if candidate is region or not candidate.bbox or _FIELD_LABEL.match(candidate.text):
+                    continue
+                c_left, c_top, c_right, c_bottom = bounds(candidate)
+                if c_bottom - c_top > height * 2:
+                    # Large background words/watermarks can overlap a small
+                    # label without being that field's value.
+                    continue
+                overlap = min(bottom, c_bottom) - max(top, c_top)
+                gap = c_left - right
+                # A long horizontal value can have a slightly different OCR
+                # angle from its short label. Its furthest corner exaggerates
+                # vertical overlap; the top-edge centre follows the text row.
+                value_top = sum(-(p[0] - origin[0]) * uy + (p[1] - origin[1]) * ux
+                                for p in candidate.bbox[:2]) / 2
+                # OCR boxes can overlap even when the printed value is to
+                # the right. Limit tolerance to a small part of the label,
+                # and require the value's centre beyond the label's edge.
+                overlap_allowance = min(height * .75, (right - left) * .25)
+                same_row = (overlap >= height * .5
+                            and -overlap_allowance <= gap < 450
+                            and (c_left + c_right) / 2 > right)
+                if same_row:
+                    crossed_label = any(
+                        other is not region
+                        and other is not candidate
+                        and other.bbox
+                        and _FIELD_LABEL.match(other.text)
+                        and (left + right) / 2 < bounds(other)[0] < (c_left + c_right) / 2
+                        and min(bottom, bounds(other)[3]) - max(top, bounds(other)[1]) >= height * .5
+                        for other in regions
+                    )
+                    if crossed_label:
+                        continue
+                    nearby.append((max(gap, 0), candidate))
+                elif -max(5, height * .35) <= value_top - bottom < max(90, height * 3) and abs(c_left - left) < 220:
+                    # A blank field must not borrow the value belonging to the
+                    # next labeled field underneath it (for example W-9 lines
+                    # 1 and 2). A label in the same column closes this field.
+                    crossed_label = any(
+                        other is not region
+                        and other.bbox
+                        and _FIELD_LABEL.match(other.text)
+                        and bottom - 5 <= bounds(other)[1] <= value_top
+                        and abs(bounds(other)[0] - left) < 220
+                        for other in regions
+                    )
+                    if crossed_label:
+                        continue
+                    nearby.append((500 + max(value_top - bottom, 0) + abs(c_left - left), candidate))
+            for _, candidate in sorted(nearby, key=lambda item: item[0]):
+                yield candidate.text, candidate
+
+
+def _put(result: StructuredExtraction, key: str, value, evidence: dict | list[dict]) -> None:
+    if value is None or value == "":
+        return
+    evidence = evidence if isinstance(evidence, list) else [evidence]
+    result.field_evidence.setdefault(key, []).extend(evidence)
+    previous = result.fields.get(key)
+    if previous is not None and re.sub(r"\W", "", str(previous)).casefold() != re.sub(r"\W", "", str(value)).casefold():
+        error = f"FIELD_MISMATCH_{key.upper()}"
+        if error not in result.errors:
+            result.errors.append(error)
+        result.checks[f"{key}_agreement"] = False
+        return
+    result.fields[key] = value
+
+
+def _visual(result: StructuredExtraction, regions: list[TextRegion], key: str, labels: tuple[str, ...], parser: Callable[[str], str | None] = _name) -> None:
+    for raw, region in _label_values(regions, labels):
+        value = parser(raw)
+        if value is not None:
+            _put(result, key, value, _evidence(region, raw))
+            return
+
+
+def _state(text: str) -> str | None:
+    upper = text.upper()
+    for code, name in _US_STATES.items():
+        if re.search(r"\b" + re.escape(name) + r"\b", upper):
+            return code
+    match = re.search(r"\bUSA\s*([A-Z]{2})\b", upper)
+    if match and match[1] in _US_STATES:
+        return match[1]
+    return None
+
+
+def _detect_text_type(regions: list[TextRegion]) -> tuple[str | None, str | None]:
+    text = "\n".join(region.text.upper() for region in regions)
+    state = _state(text)
+    if state and re.search(r"\bDRIVER(?:'S|S)? LICENSE\b", text):
+        return "us_driver_license", state
+    if state and re.search(r"\b(?:IDENTIFICATION|IDENTITY) CARD\b", text):
+        return "us_state_id", state
+    american = bool(re.search(r"\bUSCIS\b|UNITED\s*STATES", text))
+    if american and "PERMANENT RESIDENT" in text:
+        return "us_green_card", None
+    if american and "EMPLOYMENT AUTHORIZATION" in text:
+        return "us_ead", None
+    if american and "PASSPORT CARD" in text:
+        return "passport_card", None
+    if re.search(r"\bI[ -]?94\b", text) and "CLASS OF ADMISSION" in text and re.search(r"ADMISSION.*RECORD NUMBER|CUSTOMS AND BORDER|HOMELAND SECURITY", text):
+        return "us_i94", None
+    if (re.search(r"\bW[ -]?9\b", text) and "REQUEST FOR TAXPAYER" in text
+            and "IDENTIFICATION NUMBER AND CERTIFICATION" in text):
+        return "us_w9", None
+    return None, None
+
+
+def _extract_aamva(barcodes: list[BarcodeResult]) -> StructuredExtraction | None:
+    found: list[StructuredExtraction] = []
+    for barcode in barcodes:
+        if "PDF417" not in re.sub(r"[^A-Z0-9]", "", barcode.format.upper()):
+            continue
+        try:
+            parsed = parse_aamva(barcode)
+        except ValueError as error:
+            # A corrupt payload cannot confidently identify DL versus ID.
+            result = StructuredExtraction("us_driver_license", errors=[str(error)])
+            result.checks.update({"barcode_decoded": True, "barcode_structure_valid": False})
+            found.append(result)
+            continue
+        if parsed is None:
+            continue
+        raw = parsed.elements
+        raw_country = raw.get("DCG")
+        country = normalize_country(raw_country) if raw_country in ("US", "USA", "CA", "CAN") else None
+        state = raw.get("DAJ")
+        if country != "US" and not (raw_country is None and state in _US_STATES):
+            continue
+        result = StructuredExtraction(parsed.document_type, "US", state, errors=parsed.errors.copy())
+        result.checks.update({"barcode_decoded": True, "barcode_structure_valid": not parsed.errors, "aamva_version": parsed.version, "aamva_jurisdiction_version": parsed.jurisdiction_version, "aamva_issuer_id": parsed.issuer_id, "issuer_authenticated": False, "signature_verified": False})
+        evidence = {"text": barcode.text, "bbox": barcode.bbox, "source": "pdf417", "confidence": 1.0}
+        keys = {"DAQ": "document_number", "DCS": "surname", "DAB": "surname", "DAC": "first_name", "DAD": "middle_names", "DAG": "address", "DAI": "city", "DAJ": "state", "DAK": "postal_code", "DCA": "license_class", "DCB": "restrictions", "DCD": "endorsements"}
+        for element, key in keys.items():
+            if parsed.document_type == "us_state_id" and element in ("DCA", "DCB", "DCD"):
+                continue
+            if raw.get(element):
+                _put(result, key, raw[element], evidence)
+        if raw.get("DAC"):
+            _put(result, "given_names", " ".join(part for part in (raw["DAC"], raw.get("DAD")) if part), evidence)
+        for element, key in (("DBB", "date_of_birth"), ("DBA", "expiry_date"), ("DBD", "issue_date")):
+            if raw.get(element):
+                value = _us_date(raw[element])
+                if value is None:
+                    result.errors.append(f"INVALID_{key.upper()}")
+                else:
+                    _put(result, key, value, evidence)
+        if raw.get("DBC"):
+            sex = {"1": "M", "2": "F", "9": "X"}.get(raw["DBC"])
+            if sex is None:
+                result.errors.append("INVALID_SEX")
+            else:
+                _put(result, "sex", sex, evidence)
+        if state not in _US_STATES:
+            result.errors.append("INVALID_ISSUING_REGION")
+        for element in ("DDE", "DDF", "DDG"):
+            if raw.get(element) == "T":
+                result.warnings.append(f"AAMVA_NAME_TRUNCATED_{element}")
+        found.append(result)
+    if len(found) > 1:
+        found[0].errors.append("MULTIPLE_AAMVA_DOCUMENTS")
+    return found[0] if found else None
+
+
+def _identity_visual(result: StructuredExtraction, regions: list[TextRegion]) -> None:
+    _visual(result, regions, "surname", (r"surname", r"family name", r"last name", r"LN"), _person_name)
+    if result.document_type in ("us_driver_license", "us_state_id"):
+        _visual(result, regions, "given_names", (r"given names?", r"FN"), _person_name)
+        _visual(result, regions, "first_name", (r"first name",), _person_name)
+        _visual(result, regions, "middle_names", (r"middle names?",), _person_name)
+        if not result.fields.get("surname"):
+            _visual(result, regions, "surname", (r"1",), _person_name)
+        if not result.fields.get("given_names"):
+            _visual(result, regions, "given_names", (r"2",), _person_name)
+    else:
+        _visual(result, regions, "given_names", (r"given names?", r"first(?: \(given\))? name", r"FN"), _person_name)
+    _visual(result, regions, "date_of_birth", (r"(?:USA\s*)?date of birth", r"birth date(?: \([^)]*\))?", r"DOB"), _us_date)
+    _visual(result, regions, "expiry_date", (r"card expires", r"expires(?:\s*on)?", r"date of expiry", r"expiration date", r"expiry date", r"EXP"), _us_date)
+    _visual(result, regions, "sex", (r"sex",), lambda value: value.upper() if value.upper() in ("M", "F", "X") else None)
+
+
+def _extract_visual(result: StructuredExtraction, regions: list[TextRegion]) -> None:
+    kind = result.document_type
+    if kind in ("us_driver_license", "us_state_id", "passport_card", "us_green_card", "us_ead", "visa"):
+        _identity_visual(result, regions)
+    if kind in ("us_driver_license", "us_state_id", "passport_card"):
+        labels = (r"passport\s*(?:card[\s'’]*)?(?:number|no\.?)", r"card (?:number|no\.?)") if kind == "passport_card" else (r"(?:driver(?:'s)? license|license|licence|lic\.?|identification|id|dl)\s*(?:number|no\.?|#)", r"DL", r"ID")
+        _visual(result, regions, "document_number", labels, _document_number)
+        _visual(result, regions, "issue_date", (r"date of issue", r"issued(?: on)?", r"ISS"), _us_date)
+        _visual(result, regions, "address", (r"address",), lambda value: value.strip() if re.search(r"[0-9]", value) else None)
+    elif kind in ("us_green_card", "us_ead"):
+        _visual(result, regions, "uscis_number", (r"USCIS\s*#?", r"A[ -]?(?:number|#)"), _pattern(r"[0-9]{9}"))
+        _visual(result, regions, "card_number", (r"(?:category\s+)?card\s*(?:#|number|no\.?)",), _pattern(r"[A-Z]{3}[0-9]{10}"))
+        _visual(result, regions, "category", (r"category",), _pattern(r"[A-Z]{1,2}[0-9]{1,2}"))
+        _visual(result, regions, "country_of_birth", (r"country of birth",), _country_of_birth)
+        _visual(result, regions, "resident_since" if kind == "us_green_card" else "valid_from", (r"resident since",) if kind == "us_green_card" else (r"valid from",), _us_date)
+    elif kind == "us_i94":
+        _visual(result, regions, "i94_number", (r"admission\s*\(I[ -]?94\)\s*record number", r"I[ -]?94\s*(?:admission|record)?\s*(?:number|no\.?)", r"admission record number"), _pattern(r"[0-9]{9}[A-Z0-9][0-9]"))
+        _visual(result, regions, "surname", (r"last/surname", r"family name", r"surname"))
+        _visual(result, regions, "given_names", (r"first(?: \(given\))? name", r"given name"))
+        _visual(result, regions, "date_of_birth", (r"birth date(?: \([^)]*\))?", r"date of birth"), _us_date)
+        _visual(result, regions, "class_of_admission", (r"class of admission",), _pattern(r"[A-Z][A-Z0-9]{0,4}"))
+        _visual(result, regions, "admit_until", (r"admit until date(?: \([^)]*\))?", r"admit until"), lambda value: "D/S" if re.sub(r"\s", "", value.upper()) in ("D/S", "DS") else _us_date(value))
+        _visual(result, regions, "admission_date", (r"most recent date of entry", r"date of entry(?: \([^)]*\))?", r"admission date"), _us_date)
+        _visual(result, regions, "passport_number", (r"passport number",), _pattern(r"[A-Z0-9]{4,20}"))
+        _visual(result, regions, "country_of_citizenship", (r"country of citizenship",), _name)
+    elif kind == "us_w9":
+        _visual(result, regions, "name", (r"1\s+name(?: of entity/individual)?(?:\s*\([^)]*\))?", r"name(?:\s*\([^)]*\))?"))
+        _visual(result, regions, "business_name", (r"(?:2\s+)?business name(?:/disregarded entity name)?(?:,?\s+if different from above)?",))
+        _visual(result, regions, "address", (r"5\s+address(?:\s*\([^)]*\))?", r"address"), lambda value: value.strip() if re.search(r"[0-9]", value) else None)
+        _visual(result, regions, "city_state_postal_code", (r"6\s+city,?\s+state,?\s+and ZIP code", r"city,?\s+state,?\s+and ZIP code"), lambda value: value.strip() if re.search(r"\b[0-9]{5}(?:-[0-9]{4})?\b", value) else None)
+        for labels, id_type in (((r"social security number", r"SSN"), "ssn"), ((r"employer identification number", r"EIN"), "ein")):
+            for raw, region in _label_values(regions, labels):
+                digits = _compact(raw)
+                if re.fullmatch(r"[0-9]{9}", digits) and digits != "000000000":
+                    _put(result, "taxpayer_id", digits, _evidence(region, raw))
+                    _put(result, "taxpayer_id_type", id_type, _evidence(region, raw))
+                    break
+
+    if kind == "passport_card" and not result.fields.get("date_of_birth"):
+        # Some cards print sex and DOB on one baseline; OCR can merge both
+        # values into a single region. Require both labels and a strict date.
+        has_sex = any(re.fullmatch(r"sex", r.text.strip(), re.I) for r in regions)
+        if has_sex:
+            for raw, region in _label_values(regions, (r"date of birth",)):
+                match = re.fullmatch(r"([MFX])\s*(\d{1,2}\s*[A-Za-z]{3,9}\s*\d{4})", raw)
+                if match and (birth := _us_date(match[2])):
+                    _put(result, "date_of_birth", birth, _evidence(region))
+                    _put(result, "sex", match[1], _evidence(region))
+                    break
+
+
+def _finish(result: StructuredExtraction) -> StructuredExtraction:
+    profile = DOCUMENT_PROFILES[result.document_type]
+    result.missing_required_fields = [name for name in profile.required_fields if not result.fields.get(name)]
+    result.checks.setdefault("issuer_authenticated", False)
+    result.checks["required_fields_present"] = not result.missing_required_fields
+    birth, expiry = result.fields.get("date_of_birth"), result.fields.get("expiry_date")
+    if birth and date.fromisoformat(birth) > date.today():
+        result.errors.append("DATE_OF_BIRTH_IN_FUTURE")
+    if birth and expiry and expiry <= birth:
+        result.errors.append("EXPIRY_BEFORE_DATE_OF_BIRTH")
+    if expiry:
+        result.checks["printed_expiry_in_past"] = expiry < date.today().isoformat()
+    scores = [item["confidence"] for items in result.field_evidence.values() for item in items]
+    confidence = sum(scores) / len(scores) if scores else 0.0
+    result.confidence = round(min(confidence, 0.49 if result.errors else 0.69 if result.missing_required_fields else 0.99), 3)
+    result.errors = list(dict.fromkeys(result.errors))
+    result.warnings = list(dict.fromkeys(["EXPERIMENTAL_DOCUMENT_PROFILE", *result.warnings]))
+    return result
+
+
+def extract_structured_document(
+    regions: list[TextRegion],
+    *,
+    document_type: str | None = None,
+    country: str | None = None,
+    barcodes: list[BarcodeResult] | None = None,
+) -> StructuredExtraction | None:
+    """Extract a registered new profile; return None for legacy/unrecognized input."""
+    document_type, country = validate_document_hint(document_type, country)
+    if document_type and DOCUMENT_PROFILES[document_type].legacy:
+        return None
+    result = _extract_aamva(barcodes or [])
+    mrz = parse_travel_mrz(regions)
+    if result is not None and mrz is not None:
+        result.errors.append("MULTIPLE_MACHINE_READABLE_DOCUMENTS")
+    if result is None and mrz is not None:
+        result = StructuredExtraction(mrz.document_type, mrz.issuing_country, fields=mrz.fields, field_evidence=mrz.field_evidence, checks=mrz.checks, errors=mrz.errors, warnings=mrz.warnings)
+    text_type, state = _detect_text_type(regions)
+    if result is None and text_type:
+        result = StructuredExtraction(text_type, "US", state)
+    if result is None:
+        if document_type is None:
+            return None
+        result = StructuredExtraction(document_type, country, errors=["DOCUMENT_TYPE_NOT_CONFIRMED"])
+        return _finish(result)
+    if document_type is not None and result.document_type != document_type:
+        result.errors.append("DOCUMENT_TYPE_MISMATCH")
+    if country is not None and result.issuing_country is not None and result.issuing_country != country:
+        result.errors.append("DOCUMENT_COUNTRY_MISMATCH")
+    if text_type is not None and text_type != result.document_type:
+        result.errors.append("DOCUMENT_TYPE_EVIDENCE_CONFLICT")
+    _extract_visual(result, regions)
+    if result.document_type in ("us_driver_license", "us_state_id") and not result.checks.get("barcode_decoded"):
+        result.warnings.append("PDF417_NOT_DECODED")
+    return _finish(result)

package/python/core/travel_mrz.py

@@ -0,0 +1,164 @@
+"""Strict TD1 and machine-readable visa extraction, with US card profiles.
+
+Field positions follow ICAO Doc 9303 parts 5 and 7. USCIS cards expose an
+A-number in the main number field and a separate card number in optional data;
+these are intentionally not mapped to the same public field.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .document_registry import is_known_mrz_country, normalize_country
+from .mrz_parser import _DIGIT_CORRECTIONS, _clean_mrz_text, _parse_mrz_date, verify_check_digit
+from .ocr_engine import TextRegion
+
+
+@dataclass
+class TravelMRZResult:
+    document_type: str
+    issuing_country: str | None
+    fields: dict
+    field_evidence: dict
+    checks: dict
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def _name(text: str) -> str:
+    return " ".join(text.replace("<", " ").split())
+
+
+def _correct_digits(text: str, positions: list[int]) -> str:
+    values = list(text)
+    for index in positions:
+        values[index] = values[index].translate(_DIGIT_CORRECTIONS)
+    return "".join(values)
+
+
+def _country(code: str) -> str | None:
+    if code == "D<<":
+        return "DE"
+    try:
+        return normalize_country(code.replace("<", ""))
+    except ValueError:
+        return None
+
+
+def _evidence(regions: list[TextRegion]) -> list[dict]:
+    return [{"text": region.text, "bbox": region.bbox, "source": "mrz", "confidence": region.confidence} for region in regions]
+
+
+def parse_travel_mrz(regions: list[TextRegion]) -> TravelMRZResult | None:
+    """Parse a supported exact-width MRZ without padding or guessed characters."""
+    candidates: list[tuple[int, str, TextRegion]] = []
+    for region in regions:
+        for line in region.text.splitlines():
+            text = _clean_mrz_text(line)
+            if re.fullmatch(r"[A-Z0-9<]{30}|[A-Z0-9<]{36}|[A-Z0-9<]{44}", text):
+                y = min((point[1] for point in region.bbox), default=0)
+                candidates.append((y, text, region))
+    candidates.sort(key=lambda candidate: candidate[0])
+    parsed: list[TravelMRZResult] = []
+    for index, (_, first, region) in enumerate(candidates):
+        if len(first) == 30 and index + 2 < len(candidates):
+            following = candidates[index:index + 3]
+            if all(len(item[1]) == 30 for item in following):
+                prefix, issuer = first[:2], first[2:5]
+                document_type = "passport_card" if prefix == "IP" else "us_green_card" if issuer == "USA" and prefix in ("C1", "C2") else "us_ead" if issuer == "USA" and prefix == "IA" else None
+                if document_type and re.fullmatch(r"[A-Z<]{30}", following[2][1]):
+                    parsed.append(_parse_td1(document_type, [item[1] for item in following], [item[2] for item in following]))
+        elif len(first) in (36, 44) and first.startswith("V") and index + 1 < len(candidates):
+            second = candidates[index + 1]
+            if len(second[1]) == len(first) and re.fullmatch(r"V[A-Z<][A-Z<]{3}[A-Z<]+", first):
+                parsed.append(_parse_visa([first, second[1]], [region, second[2]]))
+    if not parsed:
+        return None
+    # Multiple independent documents cannot safely be collapsed into one result.
+    if len(parsed) > 1:
+        parsed[0].errors.append("MULTIPLE_MRZ_DOCUMENTS")
+    return parsed[0]
+
+
+def _finish(document_type: str, lines: list[str], regions: list[TextRegion], fields: dict, checks: dict, name_line: str) -> TravelMRZResult:
+    surname, _, given = name_line.partition("<<")
+    fields.update({"surname": _name(surname) or None, "given_names": _name(given) or None, "country_code": lines[0][2:5], "mrz_raw": lines})
+    errors = [f"MRZ_{key.upper()}_FAILED" for key, value in checks.items() if value is False]
+    warnings = []
+    for field_name in ("date_of_birth", "expiry_date"):
+        if fields.get(field_name) is None:
+            errors.append(f"MISSING_OR_INVALID_{field_name.upper()}")
+    if fields.get("sex") not in ("M", "F", "X"):
+        errors.append("INVALID_SEX")
+    issuing_country = _country(fields["country_code"])
+    if issuing_country is None:
+        errors.append("UNKNOWN_ISSUING_COUNTRY")
+    if "nationality" in fields and not is_known_mrz_country(fields["nationality"]):
+        errors.append("UNKNOWN_NATIONALITY")
+    checks["mrz_checksums_valid"] = all(checks.values())
+    checks["issuer_authenticated"] = False
+    evidence = {name: _evidence(regions) for name, value in fields.items() if value is not None}
+    return TravelMRZResult(document_type, issuing_country, fields, evidence, checks, errors, warnings)
+
+
+def _parse_td1(document_type: str, lines: list[str], regions: list[TextRegion]) -> TravelMRZResult:
+    first = _correct_digits(lines[0], [14])
+    second = _correct_digits(lines[1], list(range(0, 7)) + list(range(8, 15)) + [29])
+    surname_line = lines[2]
+    number = first[5:14]
+    number_check = first[14]
+    fields: dict = {
+        "document_number": number.rstrip("<") or None,
+        "date_of_birth": _parse_mrz_date(second[:6]),
+        "expiry_date": _parse_mrz_date(second[8:14], is_expiry=True),
+        "sex": "X" if second[7] == "<" else second[7],
+        "nationality": second[15:18].replace("<", "") or None,
+    }
+    # ICAO TD1 extended document numbers move their check digit into optional
+    # data, immediately after the continuation and before a filler.
+    if document_type == "passport_card" and number_check == "<":
+        continuation = first[15:30].split("<", 1)[0]
+        if len(continuation) >= 2 and continuation[-1].isdigit():
+            number += continuation[:-1]
+            number_check = continuation[-1]
+            fields["document_number"] = number
+    checks = {
+        "document_number_checksum": verify_check_digit(number, number_check),
+        "date_of_birth_checksum": verify_check_digit(second[:6], second[6]),
+        "expiry_date_checksum": verify_check_digit(second[8:14], second[14]),
+        "composite_checksum": verify_check_digit(first[5:30] + second[:7] + second[8:15] + second[18:29], second[29]),
+    }
+    if document_type in ("us_green_card", "us_ead"):
+        fields.pop("document_number")
+        fields.pop("nationality")
+        fields["uscis_number"] = number.rstrip("<")
+        fields["card_number"] = first[15:30].rstrip("<") or None
+        # US profiles encode country of birth here, not citizenship.
+        fields["country_of_birth"] = second[15:18].replace("<", "") or None
+    result = _finish(document_type, [first, second, surname_line], regions, fields, checks, surname_line)
+    if document_type in ("us_green_card", "us_ead"):
+        if not re.fullmatch(r"[0-9]{9}", fields["uscis_number"] or ""):
+            result.errors.append("INVALID_USCIS_NUMBER")
+        if not re.fullmatch(r"[A-Z]{3}[0-9]{10}", fields["card_number"] or ""):
+            result.errors.append("INVALID_CARD_NUMBER")
+    return result
+
+
+def _parse_visa(lines: list[str], regions: list[TextRegion]) -> TravelMRZResult:
+    first, second = lines
+    second = _correct_digits(second, [9] + list(range(13, 20)) + list(range(21, 28)))
+    fields = {
+        "document_number": second[:9].rstrip("<") or None,
+        "date_of_birth": _parse_mrz_date(second[13:19]),
+        "expiry_date": _parse_mrz_date(second[21:27], is_expiry=True),
+        "nationality": second[10:13].replace("<", "") or None,
+        "sex": "X" if second[20] == "<" else second[20],
+        "mrz_format": "MRV_A" if len(first) == 44 else "MRV_B",
+    }
+    checks = {
+        "document_number_checksum": verify_check_digit(second[:9], second[9]),
+        "date_of_birth_checksum": verify_check_digit(second[13:19], second[19]),
+        "expiry_date_checksum": verify_check_digit(second[21:27], second[27]),
+    }
+    return _finish("visa", [first, second], regions, fields, checks, first[5:])