ocr-postprocess 0.1.0__py3-none-any.whl

ocr_postprocess/extractors/pattern/cccd.py

@@ -0,0 +1,120 @@
+"""Pattern extractor: CCCD (Căn cước công dân) 12-digit numbers."""
+
+from __future__ import annotations
+
+import regex as re
+
+from ocr_postprocess.extractors.base import PatternExtractor
+from ocr_postprocess.extractors.registry import register
+from ocr_postprocess.models import Candidate, PipelineContext
+
+# Province codes (first 3 digits of CCCD = province code * 1 or gender)
+# Digits 1-3 encode: province code (001-096 range)
+# Valid province codes in Vietnam
+_VALID_PROVINCE_CODES = {
+    "001",
+    "002",
+    "004",
+    "006",
+    "008",
+    "010",
+    "011",
+    "012",
+    "014",
+    "015",
+    "017",
+    "019",
+    "020",
+    "022",
+    "024",
+    "025",
+    "026",
+    "027",
+    "030",
+    "031",
+    "033",
+    "034",
+    "035",
+    "036",
+    "037",
+    "038",
+    "040",
+    "042",
+    "044",
+    "045",
+    "046",
+    "048",
+    "049",
+    "051",
+    "052",
+    "054",
+    "056",
+    "058",
+    "060",
+    "062",
+    "064",
+    "066",
+    "067",
+    "068",
+    "070",
+    "072",
+    "074",
+    "075",
+    "077",
+    "079",
+    "080",
+    "082",
+    "083",
+    "084",
+    "086",
+    "087",
+    "089",
+    "091",
+    "092",
+    "093",
+    "094",
+    "095",
+    "096",
+}
+
+_PATTERN = re.compile(r"\b(\d{12})\b")
+
+
+def _validate_cccd(number: str) -> tuple[bool, str]:
+    """Validate CCCD structure. Returns (is_valid, reason)."""
+    if len(number) != 12 or not number.isdigit():
+        return False, "not 12 digits"
+    province = number[:3]
+    if province not in _VALID_PROVINCE_CODES:
+        return False, f"invalid province code {province}"
+    return True, "ok"
+
+
+@register("cccd")
+class CccdExtractor(PatternExtractor):
+    """Extract 12-digit CCCD numbers with province code validation."""
+
+    pattern = r"\b\d{12}\b"
+
+    def extract(self, ctx: PipelineContext, field=None) -> list[Candidate]:
+        text = ctx.normalized_text or ctx.raw_text
+        candidates: list[Candidate] = []
+
+        for m in _PATTERN.finditer(text):
+            value = m.group(0)
+            valid, reason = _validate_cccd(value)
+            confidence = 0.95 if valid else 0.7
+            key = field.key if field else "cccd"
+            candidates.append(
+                Candidate(
+                    key=key,
+                    value=value,
+                    raw=value,
+                    extractor="cccd",
+                    sources=["pattern:cccd"] + (["pattern:cccd:checksum"] if valid else []),
+                    span=(m.start(), m.end()),
+                    confidence=confidence,
+                    notes=[] if valid else [f"province code validation: {reason}"],
+                )
+            )
+        return candidates

ocr_postprocess/extractors/pattern/cmnd.py

@@ -0,0 +1,38 @@
+"""Pattern extractor: CMND (9-digit old ID card)."""
+
+from __future__ import annotations
+
+import regex as re
+
+from ocr_postprocess.extractors.base import PatternExtractor
+from ocr_postprocess.extractors.registry import register
+from ocr_postprocess.models import Candidate, PipelineContext
+
+_PATTERN_9 = re.compile(r"\b(\d{9})\b")
+
+
+@register("cmnd")
+class CmndExtractor(PatternExtractor):
+    """Extract 9-digit CMND (old Vietnamese ID card) numbers."""
+
+    pattern = r"\b\d{9}\b"
+
+    def extract(self, ctx: PipelineContext, field=None) -> list[Candidate]:
+        text = ctx.normalized_text or ctx.raw_text
+        candidates: list[Candidate] = []
+        key = field.key if field else "cmnd"
+
+        for m in _PATTERN_9.finditer(text):
+            value = m.group(0)
+            candidates.append(
+                Candidate(
+                    key=key,
+                    value=value,
+                    raw=value,
+                    extractor="cmnd",
+                    sources=["pattern:cmnd"],
+                    span=(m.start(), m.end()),
+                    confidence=0.85,
+                )
+            )
+        return candidates

ocr_postprocess/extractors/pattern/currency_vnd.py

@@ -0,0 +1,48 @@
+"""Pattern extractor: Vietnamese currency (VND)."""
+
+from __future__ import annotations
+
+import regex as re
+
+from ocr_postprocess.extractors.base import PatternExtractor
+from ocr_postprocess.extractors.registry import register
+from ocr_postprocess.models import Candidate, PipelineContext
+
+_PATTERN = re.compile(r"[\d.,]+\s*(?:đ|đồng|VND|VNĐ)\b", re.IGNORECASE)
+
+
+def _parse_amount(raw: str) -> int | None:
+    cleaned = re.sub(r"[đồng VNĐvnd\s]", "", raw, flags=re.IGNORECASE)
+    cleaned = cleaned.replace(".", "").replace(",", "")
+    try:
+        return int(cleaned)
+    except (ValueError, TypeError):
+        return None
+
+
+@register("currency_vnd")
+class CurrencyVndExtractor(PatternExtractor):
+    """Extract Vietnamese Dong currency amounts."""
+
+    pattern = r"[\d.,]+\s*(?:đ|đồng|VND|VNĐ)\b"
+
+    def extract(self, ctx: PipelineContext, field=None) -> list[Candidate]:
+        text = ctx.normalized_text or ctx.raw_text
+        candidates: list[Candidate] = []
+        key = field.key if field else "currency_vnd"
+
+        for m in _PATTERN.finditer(text):
+            raw = m.group(0)
+            amount = _parse_amount(raw)
+            candidates.append(
+                Candidate(
+                    key=key,
+                    value=amount,
+                    raw=raw,
+                    extractor="currency_vnd",
+                    sources=["pattern:currency_vnd"],
+                    span=(m.start(), m.end()),
+                    confidence=0.9,
+                )
+            )
+        return candidates

ocr_postprocess/extractors/pattern/date.py

@@ -0,0 +1,89 @@
+"""Pattern extractor: dates in Vietnamese and ISO formats."""
+
+from __future__ import annotations
+
+import logging
+
+import regex as re
+from dateutil import parser as dateutil_parser
+
+from ocr_postprocess.extractors.base import PatternExtractor
+from ocr_postprocess.extractors.registry import register
+from ocr_postprocess.models import Candidate, PipelineContext
+
+logger = logging.getLogger(__name__)
+
+# DD/MM/YYYY, DD-MM-YYYY, DD.MM.YYYY
+_SLASH = re.compile(r"\b(\d{1,2})[/\-.](\d{1,2})[/\-.](\d{4})\b")
+# YYYY-MM-DD
+_ISO = re.compile(r"\b((?:19|20)\d{2})-(\d{2})-(\d{2})\b")
+# ngày DD tháng MM năm YYYY
+_VN = re.compile(
+    r"ngày\s+(\d{1,2})\s+tháng\s+(\d{1,2})\s+năm\s+((?:19|20)\d{2})",
+    re.IGNORECASE,
+)
+
+
+def _parse_date(day: str, month: str, year: str) -> str | None:
+    try:
+        dt = dateutil_parser.parse(f"{year}-{month}-{day}", dayfirst=False)
+        return dt.date().isoformat()
+    except (ValueError, TypeError):
+        return None
+
+
+@register("date")
+class DateExtractor(PatternExtractor):
+    """Extract dates in Vietnamese and international formats."""
+
+    pattern = r"\b\d{1,2}[/\-.]\d{1,2}[/\-.]\d{4}\b"
+
+    def extract(self, ctx: PipelineContext, field=None) -> list[Candidate]:
+        text = ctx.normalized_text or ctx.raw_text
+        candidates: list[Candidate] = []
+        key = field.key if field else "date"
+        seen_spans: set[tuple[int, int]] = set()
+
+        def add(m: re.Match, day: str, month: str, year: str, confidence: float) -> None:
+            span = (m.start(), m.end())
+            if span in seen_spans:
+                return
+            seen_spans.add(span)
+            iso = _parse_date(day, month, year)
+            if iso:
+                candidates.append(
+                    Candidate(
+                        key=key,
+                        value=iso,
+                        raw=m.group(0),
+                        extractor="date",
+                        sources=["pattern:date"],
+                        span=span,
+                        confidence=confidence,
+                    )
+                )
+
+        for m in _SLASH.finditer(text):
+            add(m, m.group(1), m.group(2), m.group(3), 0.95)
+
+        for m in _ISO.finditer(text):
+            iso = f"{m.group(1)}-{m.group(2)}-{m.group(3)}"
+            span = (m.start(), m.end())
+            if span not in seen_spans:
+                seen_spans.add(span)
+                candidates.append(
+                    Candidate(
+                        key=key,
+                        value=iso,
+                        raw=m.group(0),
+                        extractor="date",
+                        sources=["pattern:date"],
+                        span=span,
+                        confidence=0.95,
+                    )
+                )
+
+        for m in _VN.finditer(text):
+            add(m, m.group(1), m.group(2), m.group(3), 0.9)
+
+        return candidates

ocr_postprocess/extractors/pattern/email.py

@@ -0,0 +1,38 @@
+"""Pattern extractor: email addresses."""
+
+from __future__ import annotations
+
+import regex as re
+
+from ocr_postprocess.extractors.base import PatternExtractor
+from ocr_postprocess.extractors.registry import register
+from ocr_postprocess.models import Candidate, PipelineContext
+
+_PATTERN = re.compile(r"[\w.+\-]+@[\w\-]+\.[\w.\-]+")
+
+
+@register("email")
+class EmailExtractor(PatternExtractor):
+    """Extract email addresses."""
+
+    pattern = r"[\w.+\-]+@[\w\-]+\.[\w.\-]+"
+
+    def extract(self, ctx: PipelineContext, field=None) -> list[Candidate]:
+        text = ctx.normalized_text or ctx.raw_text
+        candidates: list[Candidate] = []
+        key = field.key if field else "email"
+
+        for m in _PATTERN.finditer(text):
+            value = m.group(0).lower()
+            candidates.append(
+                Candidate(
+                    key=key,
+                    value=value,
+                    raw=m.group(0),
+                    extractor="email",
+                    sources=["pattern:email"],
+                    span=(m.start(), m.end()),
+                    confidence=0.95,
+                )
+            )
+        return candidates

ocr_postprocess/extractors/pattern/gender_vn.py

@@ -0,0 +1,48 @@
+"""Pattern extractor: Vietnamese gender."""
+
+from __future__ import annotations
+
+import regex as re
+
+from ocr_postprocess.extractors.base import PatternExtractor
+from ocr_postprocess.extractors.registry import register
+from ocr_postprocess.models import Candidate, PipelineContext
+
+_PATTERN = re.compile(r"\b(Nam|Nữ|Male|Female|[MF])\b")
+
+_NORMALIZE: dict[str, str] = {
+    "nam": "Nam",
+    "male": "Nam",
+    "m": "Nam",
+    "nữ": "Nữ",
+    "female": "Nữ",
+    "f": "Nữ",
+}
+
+
+@register("gender_vn")
+class GenderVnExtractor(PatternExtractor):
+    """Extract gender in Vietnamese or English."""
+
+    pattern = r"\b(Nam|Nữ|Male|Female|[MF])\b"
+
+    def extract(self, ctx: PipelineContext, field=None) -> list[Candidate]:
+        text = ctx.normalized_text or ctx.raw_text
+        candidates: list[Candidate] = []
+        key = field.key if field else "gender_vn"
+
+        for m in _PATTERN.finditer(text):
+            raw = m.group(0)
+            value = _NORMALIZE.get(raw.lower(), raw)
+            candidates.append(
+                Candidate(
+                    key=key,
+                    value=value,
+                    raw=raw,
+                    extractor="gender_vn",
+                    sources=["pattern:gender_vn"],
+                    span=(m.start(), m.end()),
+                    confidence=0.9,
+                )
+            )
+        return candidates

ocr_postprocess/extractors/pattern/phone_vn.py

@@ -0,0 +1,83 @@
+"""Pattern extractor: Vietnamese phone numbers."""
+
+from __future__ import annotations
+
+import regex as re
+
+from ocr_postprocess.extractors.base import PatternExtractor
+from ocr_postprocess.extractors.registry import register
+from ocr_postprocess.models import Candidate, PipelineContext
+
+_PATTERN = re.compile(r"(?:\+84|0)(?:3[2-9]|5[6-9]|7[06-9]|8[1-9]|9[0-9])\d{7}\b")
+
+_VALID_PREFIXES = {
+    "032",
+    "033",
+    "034",
+    "035",
+    "036",
+    "037",
+    "038",
+    "039",  # Viettel
+    "056",
+    "058",  # Vietnamobile
+    "070",
+    "076",
+    "077",
+    "078",
+    "079",  # Mobifone
+    "081",
+    "082",
+    "083",
+    "084",
+    "085",
+    "086",
+    "089",  # Vinaphone / others
+    "090",
+    "091",
+    "092",
+    "093",
+    "094",
+    "095",
+    "096",
+    "097",
+    "098",
+    "099",
+}
+
+
+def _normalize_phone(raw: str) -> str:
+    """Convert +84xxx to 0xxx."""
+    if raw.startswith("+84"):
+        return "0" + raw[3:]
+    return raw
+
+
+@register("phone_vn")
+class PhoneVnExtractor(PatternExtractor):
+    """Extract Vietnamese mobile phone numbers."""
+
+    pattern = r"(?:\+84|0)(?:3[2-9]|5[6-9]|7[06-9]|8[1-9]|9[0-9])\d{7}"
+
+    def extract(self, ctx: PipelineContext, field=None) -> list[Candidate]:
+        text = ctx.normalized_text or ctx.raw_text
+        candidates: list[Candidate] = []
+        key = field.key if field else "phone_vn"
+
+        for m in _PATTERN.finditer(text):
+            raw = m.group(0)
+            normalized = _normalize_phone(raw)
+            prefix = normalized[:3]
+            valid = prefix in _VALID_PREFIXES
+            candidates.append(
+                Candidate(
+                    key=key,
+                    value=normalized,
+                    raw=raw,
+                    extractor="phone_vn",
+                    sources=["pattern:phone_vn"],
+                    span=(m.start(), m.end()),
+                    confidence=0.95 if valid else 0.8,
+                )
+            )
+        return candidates

ocr_postprocess/extractors/pattern/plate_vn.py

@@ -0,0 +1,39 @@
+"""Pattern extractor: Vietnamese vehicle plate numbers."""
+
+from __future__ import annotations
+
+import regex as re
+
+from ocr_postprocess.extractors.base import PatternExtractor
+from ocr_postprocess.extractors.registry import register
+from ocr_postprocess.models import Candidate, PipelineContext
+
+# e.g. 30A-12345, 15H-087.71, 51F1-12345
+_PATTERN = re.compile(r"\b\d{2}[A-Z]{1,2}[-\s]?\d{3,5}(?:[.\-]\d{1,2})?\b")
+
+
+@register("plate_vn")
+class PlateVnExtractor(PatternExtractor):
+    """Extract Vietnamese vehicle plate numbers."""
+
+    pattern = r"\b\d{2}[A-Z]{1,2}[-\s]?\d{3,5}(?:[.\-]\d{1,2})?\b"
+
+    def extract(self, ctx: PipelineContext, field=None) -> list[Candidate]:
+        text = ctx.normalized_text or ctx.raw_text
+        candidates: list[Candidate] = []
+        key = field.key if field else "plate_vn"
+
+        for m in _PATTERN.finditer(text):
+            value = m.group(0).strip()
+            candidates.append(
+                Candidate(
+                    key=key,
+                    value=value,
+                    raw=value,
+                    extractor="plate_vn",
+                    sources=["pattern:plate_vn"],
+                    span=(m.start(), m.end()),
+                    confidence=0.9,
+                )
+            )
+        return candidates

ocr_postprocess/extractors/pattern/tax_code.py

@@ -0,0 +1,53 @@
+"""Pattern extractor: Vietnamese tax codes."""
+
+from __future__ import annotations
+
+import regex as re
+
+from ocr_postprocess.extractors.base import PatternExtractor
+from ocr_postprocess.extractors.registry import register
+from ocr_postprocess.models import Candidate, PipelineContext
+
+_PATTERN = re.compile(r"\b(\d{10})(?:-(\d{3}))?\b")
+
+
+def _validate_tax_code(code: str) -> bool:
+    """Validate 10-digit tax code checksum (TT 105/2020/TT-BTC)."""
+    if len(code) != 10 or not code.isdigit():
+        return False
+    weights = [31, 29, 23, 19, 17, 13, 7, 5, 3]
+    total = sum(int(code[i]) * weights[i] for i in range(9))
+    check = 10 - (total % 11)
+    if check == 10:
+        check = 0
+    return check == int(code[9])
+
+
+@register("tax_code")
+class TaxCodeExtractor(PatternExtractor):
+    """Extract Vietnamese tax codes with checksum validation."""
+
+    pattern = r"\b\d{10}(?:-\d{3})?\b"
+
+    def extract(self, ctx: PipelineContext, field=None) -> list[Candidate]:
+        text = ctx.normalized_text or ctx.raw_text
+        candidates: list[Candidate] = []
+        key = field.key if field else "tax_code"
+
+        for m in _PATTERN.finditer(text):
+            code = m.group(1)
+            suffix = m.group(2)
+            value = f"{code}-{suffix}" if suffix else code
+            valid = _validate_tax_code(code)
+            candidates.append(
+                Candidate(
+                    key=key,
+                    value=value,
+                    raw=value,
+                    extractor="tax_code",
+                    sources=["pattern:tax_code"] + (["pattern_with_checksum"] if valid else []),
+                    span=(m.start(), m.end()),
+                    confidence=0.95 if valid else 0.7,
+                )
+            )
+        return candidates

ocr_postprocess/extractors/registry.py

@@ -0,0 +1,45 @@
+"""Extractor registry."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from ocr_postprocess.exceptions import ExtractorNotFoundError
+
+if TYPE_CHECKING:
+    from ocr_postprocess.extractors.base import Extractor
+
+logger = logging.getLogger(__name__)
+
+_REGISTRY: dict[str, type[Extractor]] = {}
+
+
+def register(name: str):
+    """Decorator to register an extractor class under a name."""
+
+    def deco(cls):
+        if name in _REGISTRY:
+            logger.warning("Overwriting extractor registration: %s", name)
+        _REGISTRY[name] = cls
+        cls.name = name
+        return cls
+
+    return deco
+
+
+def get(name: str) -> type[Extractor]:
+    """Return registered extractor class by name."""
+    if name not in _REGISTRY:
+        raise ExtractorNotFoundError(f"Extractor '{name}' not registered")
+    return _REGISTRY[name]
+
+
+def get_instance(name: str) -> Extractor:
+    """Return an instantiated extractor."""
+    return get(name)()
+
+
+def all_names() -> list[str]:
+    """Return all registered extractor names."""
+    return list(_REGISTRY.keys())