onflow-awb-ocr 0.1.0__tar.gz

onflow_awb_ocr-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: onflow-awb-ocr
+Version: 0.1.0
+Summary: Python SDK for extracting receiver information from AWB/shipping labels.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: PyMuPDF>=1.20
+Requires-Dist: requests>=2.25
+Provides-Extra: ocr
+Requires-Dist: opencv-python>=4.5; extra == "ocr"
+Requires-Dist: pytesseract>=0.3; extra == "ocr"
+Requires-Dist: numpy>=1.21; extra == "ocr"
+
+# Onflow AWB OCR
+
+Python SDK for extracting receiver information from AWB and shipping label files.
+
+The package supports PDF files with a text layer first, then falls back to OCR for
+scanned PDFs and image files when OCR dependencies are installed.
+
+## Requirements
+
+- Python 3.8+
+- PyMuPDF for PDF text-layer extraction
+- Optional OCR stack for scanned files and images:
+  - Tesseract OCR
+  - Vietnamese Tesseract language data
+  - Poppler `pdftoppm`
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install onflow-awb-ocr
+```
+
+Install with OCR dependencies:
+
+```bash
+pip install "onflow-awb-ocr[ocr]"
+```
+
+On Ubuntu, install the native OCR tools:
+
+```bash
+sudo apt install -y tesseract-ocr tesseract-ocr-vie poppler-utils
+```
+
+For local development:
+
+```bash
+pip install -e ".[ocr]"
+```
+
+## Usage
+
+```python
+from onflow_awb_ocr import OnflowAwbOcr
+
+ocr = OnflowAwbOcr(lang="vie+eng")
+result = ocr.extract("label.pdf")
+
+print(result)
+```
+
+Example result:
+
+```python
+{
+    "name": "Nguyen Van A",
+    "address": "123 Nguyen Trai\nQuan 1, TP. Ho Chi Minh",
+    "strategy": "shopee",
+}
+```
+
+If no receiver can be detected, `extract()` returns `None`.
+
+## Supported Inputs
+
+`extract()` accepts:
+
+- Local file path as `str`
+- Local file path as `pathlib.Path`
+- HTTP/HTTPS URL
+- `bytes`
+- `bytearray`
+- Binary file-like object
+
+Examples:
+
+```python
+from pathlib import Path
+
+from onflow_awb_ocr import OnflowAwbOcr
+
+ocr = OnflowAwbOcr()
+
+from_path = ocr.extract(Path("label.pdf"))
+from_url = ocr.extract("https://example.com/label.pdf")
+
+with open("label.pdf", "rb") as file:
+    from_file = ocr.extract(file)
+
+with open("label.png", "rb") as file:
+    from_bytes = ocr.extract(file.read())
+```
+
+## Compatibility
+
+The old `ReceiverExtractor` class name is still available as an alias:
+
+```python
+from onflow_awb_ocr import ReceiverExtractor
+
+ocr = ReceiverExtractor()
+result = ocr.extract("label.pdf")
+```
+
+## Package Structure
+
+- `extractor.py`: public `OnflowAwbOcr` class
+- `input.py`: input preparation for paths, URLs, bytes, and binary streams
+- `text_layer.py`: PDF text-layer extraction strategies
+- `ocr.py`: OCR fallback for scanned PDFs and images
+- `postprocess.py`: address cleanup
+- `types.py`, `constants.py`, `utils.py`: shared types, constants, and helpers
+
+## Publishing
+
+GitHub Actions builds and publishes the package to PyPI on every push to `main`.
+
+The repository must define this GitHub secret:
+
+```text
+PYPI_API_TOKEN
+```
+
+PyPI does not allow replacing an existing version. If a commit on `main` does not
+bump `project.version` in `pyproject.toml`, the publish step skips the existing
+distribution.

onflow_awb_ocr-0.1.0/README.md

@@ -0,0 +1,128 @@
+# Onflow AWB OCR
+
+Python SDK for extracting receiver information from AWB and shipping label files.
+
+The package supports PDF files with a text layer first, then falls back to OCR for
+scanned PDFs and image files when OCR dependencies are installed.
+
+## Requirements
+
+- Python 3.8+
+- PyMuPDF for PDF text-layer extraction
+- Optional OCR stack for scanned files and images:
+  - Tesseract OCR
+  - Vietnamese Tesseract language data
+  - Poppler `pdftoppm`
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install onflow-awb-ocr
+```
+
+Install with OCR dependencies:
+
+```bash
+pip install "onflow-awb-ocr[ocr]"
+```
+
+On Ubuntu, install the native OCR tools:
+
+```bash
+sudo apt install -y tesseract-ocr tesseract-ocr-vie poppler-utils
+```
+
+For local development:
+
+```bash
+pip install -e ".[ocr]"
+```
+
+## Usage
+
+```python
+from onflow_awb_ocr import OnflowAwbOcr
+
+ocr = OnflowAwbOcr(lang="vie+eng")
+result = ocr.extract("label.pdf")
+
+print(result)
+```
+
+Example result:
+
+```python
+{
+    "name": "Nguyen Van A",
+    "address": "123 Nguyen Trai\nQuan 1, TP. Ho Chi Minh",
+    "strategy": "shopee",
+}
+```
+
+If no receiver can be detected, `extract()` returns `None`.
+
+## Supported Inputs
+
+`extract()` accepts:
+
+- Local file path as `str`
+- Local file path as `pathlib.Path`
+- HTTP/HTTPS URL
+- `bytes`
+- `bytearray`
+- Binary file-like object
+
+Examples:
+
+```python
+from pathlib import Path
+
+from onflow_awb_ocr import OnflowAwbOcr
+
+ocr = OnflowAwbOcr()
+
+from_path = ocr.extract(Path("label.pdf"))
+from_url = ocr.extract("https://example.com/label.pdf")
+
+with open("label.pdf", "rb") as file:
+    from_file = ocr.extract(file)
+
+with open("label.png", "rb") as file:
+    from_bytes = ocr.extract(file.read())
+```
+
+## Compatibility
+
+The old `ReceiverExtractor` class name is still available as an alias:
+
+```python
+from onflow_awb_ocr import ReceiverExtractor
+
+ocr = ReceiverExtractor()
+result = ocr.extract("label.pdf")
+```
+
+## Package Structure
+
+- `extractor.py`: public `OnflowAwbOcr` class
+- `input.py`: input preparation for paths, URLs, bytes, and binary streams
+- `text_layer.py`: PDF text-layer extraction strategies
+- `ocr.py`: OCR fallback for scanned PDFs and images
+- `postprocess.py`: address cleanup
+- `types.py`, `constants.py`, `utils.py`: shared types, constants, and helpers
+
+## Publishing
+
+GitHub Actions builds and publishes the package to PyPI on every push to `main`.
+
+The repository must define this GitHub secret:
+
+```text
+PYPI_API_TOKEN
+```
+
+PyPI does not allow replacing an existing version. If a commit on `main` does not
+bump `project.version` in `pyproject.toml`, the publish step skips the existing
+distribution.

onflow_awb_ocr-0.1.0/onflow_awb_ocr/__init__.py

@@ -0,0 +1,11 @@
+"""Python SDK for extracting receiver information from AWB/shipping labels."""
+
+from .extractor import OnflowAwbOcr, ReceiverExtractor
+from .types import FileInput, ReceiverResult
+
+__all__ = [
+    "FileInput",
+    "OnflowAwbOcr",
+    "ReceiverExtractor",
+    "ReceiverResult",
+]

onflow_awb_ocr-0.1.0/onflow_awb_ocr/constants.py

@@ -0,0 +1,48 @@
+"""Static extraction constants."""
+
+
+HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/124.0.0.0 Safari/537.36"
+    )
+}
+
+STOP_KEYWORDS = [
+    "nội dung hàng",
+    "tổng sl",
+    "ngày đặt hàng",
+    "khối lượng",
+    "tiền thu",
+    "cod",
+    "chữ ký",
+    "mã vận đơn",
+    "mã đơn hàng",
+    "chỉ dẫn giao hàng",
+    "xác nhận",
+    "chuyển hoàn",
+    "lưu kho",
+    "người gửi",
+    "spx tuyển",
+    "hc-",
+    "in transit",
+    "product name",
+    "tên sản phẩm",
+    "ghi chú",
+    "trọng lượng",
+    "order id",
+    "thời gian",
+    "được đồng kiểm",
+    "không đồng kiểm",
+    "lex",
+    "lazada",
+    "shopee",
+    "tiktok",
+    "j&t",
+    "viettel",
+    "thu hộ",
+    "non-cod",
+    "đã thanh toán",
+    "được mở hàng",
+]

onflow_awb_ocr-0.1.0/onflow_awb_ocr/extractor.py

@@ -0,0 +1,36 @@
+"""Public SDK class."""
+
+from pathlib import Path
+from typing import Optional
+
+from .input import prepare_input
+from .ocr import extract_from_ocr
+from .postprocess import post_process
+from .text_layer import extract_from_text_layer
+from .types import FileInput, ReceiverResult
+
+
+class OnflowAwbOcr:
+    """Reusable SDK client for extracting receiver name and address."""
+
+    def __init__(self, lang: str = "vie+eng") -> None:
+        self.lang = lang
+
+    def extract(self, source: FileInput, lang: Optional[str] = None) -> Optional[ReceiverResult]:
+        prepared = prepare_input(source)
+        try:
+            result = self._extract_from_path(prepared.path, lang or self.lang)
+            return post_process(result)
+        finally:
+            prepared.cleanup()
+
+    def _extract_from_path(self, file_path: str, lang: str) -> Optional[ReceiverResult]:
+        if Path(file_path).suffix.lower() == ".pdf":
+            result = extract_from_text_layer(file_path)
+            if result:
+                return result
+
+        return extract_from_ocr(file_path, lang)
+
+
+ReceiverExtractor = OnflowAwbOcr

onflow_awb_ocr-0.1.0/onflow_awb_ocr/input.py

@@ -0,0 +1,116 @@
+"""Input preparation for path, URL, and binary SDK sources."""
+
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO, Optional, Union
+from urllib.parse import urlparse
+
+from .constants import HEADERS
+from .types import FileInput
+from .utils import is_url
+
+_CONTENT_TYPE_SUFFIXES = {
+    "pdf": ".pdf",
+    "png": ".png",
+    "jpeg": ".jpg",
+    "jpg": ".jpg",
+    "gif": ".gif",
+    "tiff": ".tif",
+    "bmp": ".bmp",
+}
+
+_MAGIC_SUFFIXES = (
+    (b"%PDF", ".pdf"),
+    (b"\x89PNG\r\n\x1a\n", ".png"),
+    (b"\xff\xd8\xff", ".jpg"),
+    (b"GIF87a", ".gif"),
+    (b"GIF89a", ".gif"),
+    (b"II*\x00", ".tif"),
+    (b"MM\x00*", ".tif"),
+    (b"BM", ".bmp"),
+)
+
+
+def guess_suffix_from_bytes(data: bytes) -> str:
+    for magic, suffix in _MAGIC_SUFFIXES:
+        if data.startswith(magic):
+            return suffix
+    return ".bin"
+
+
+def write_bytes_to_temp(data: bytes, suffix: Optional[str] = None) -> str:
+    tmp = tempfile.NamedTemporaryFile(
+        suffix=suffix or guess_suffix_from_bytes(data),
+        delete=False,
+    )
+    with tmp:
+        tmp.write(data)
+    return tmp.name
+
+
+def read_binary_source(source: Union[bytes, bytearray, BinaryIO]) -> bytes:
+    if isinstance(source, bytes):
+        return source
+    if isinstance(source, bytearray):
+        return bytes(source)
+
+    data = source.read()
+    if isinstance(data, str):
+        raise TypeError("Binary file-like input must return bytes, not str.")
+    if not isinstance(data, (bytes, bytearray)):
+        raise TypeError("Binary file-like input must return bytes.")
+    return bytes(data)
+
+
+def suffix_from_response(url: str, content_type: str) -> Optional[str]:
+    content_type = content_type.lower()
+    for marker, suffix in _CONTENT_TYPE_SUFFIXES.items():
+        if marker in content_type:
+            return suffix
+
+    suffix = Path(urlparse(url).path).suffix
+    return suffix or None
+
+
+def download_to_temp(url: str) -> str:
+    try:
+        import requests
+    except ImportError as exc:
+        raise RuntimeError("requests is required to read URL inputs.") from exc
+
+    response = requests.get(url, headers=HEADERS, timeout=30)
+    response.raise_for_status()
+    suffix = suffix_from_response(url, response.headers.get("Content-Type", ""))
+    return write_bytes_to_temp(response.content, suffix)
+
+
+@dataclass(frozen=True)
+class PreparedInput:
+    path: str
+    should_cleanup: bool
+
+    def cleanup(self) -> None:
+        if not self.should_cleanup:
+            return
+        try:
+            os.unlink(self.path)
+        except FileNotFoundError:
+            pass
+
+
+def prepare_input(source: FileInput) -> PreparedInput:
+    if isinstance(source, Path):
+        return PreparedInput(str(source), False)
+
+    if isinstance(source, str):
+        if is_url(source):
+            return PreparedInput(download_to_temp(source), True)
+        return PreparedInput(source, False)
+
+    if isinstance(source, (bytes, bytearray)) or hasattr(source, "read"):
+        data = read_binary_source(source)  # type: ignore[arg-type]
+        return PreparedInput(write_bytes_to_temp(data), True)
+
+    raise TypeError("source must be a path, URL, bytes, bytearray, or binary file-like object.")

onflow_awb_ocr-0.1.0/onflow_awb_ocr/ocr.py

@@ -0,0 +1,130 @@
+"""OCR fallback extraction."""
+
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from .types import ReceiverResult
+from .utils import is_stop
+
+_ANCHOR_RE = re.compile(
+    r"(Đến|Den|To|Receiver|Recipient|Ng[uư][ờơ]i\s*nh[ậa]n)",
+    re.IGNORECASE,
+)
+_ANCHOR_PREFIX_RE = re.compile(
+    r"^(Đến|Den|To|Receiver|Recipient|Ng[uư][ờơ]i\s*nh[ậa]n)\s*[:：-]?\s*",
+    re.IGNORECASE,
+)
+_OCR_SCALE = 2.0
+_MIN_CONFIDENCE = 20
+
+
+def load_images_for_ocr(file_path: str) -> List[Any]:
+    try:
+        import cv2
+    except ImportError:
+        return []
+
+    path = Path(file_path)
+    if path.suffix.lower() == ".pdf":
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            prefix = Path(tmp_dir) / "page"
+            try:
+                subprocess.run(
+                    ["pdftoppm", "-jpeg", "-r", "200", file_path, str(prefix)],
+                    check=True,
+                    capture_output=True,
+                )
+            except (FileNotFoundError, subprocess.CalledProcessError):
+                return []
+            files = sorted(Path(tmp_dir).glob("page-*.jpg"))
+            images = [cv2.imread(str(file)) for file in files]
+            return [image for image in images if image is not None]
+
+    image = cv2.imread(file_path)
+    return [image] if image is not None else []
+
+
+def parse_confidence(value: Any) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return -1
+
+
+def extract_from_ocr(file_path: str, lang: str = "vie+eng") -> Optional[ReceiverResult]:
+    try:
+        import cv2
+        import pytesseract
+        from pytesseract import Output
+    except ImportError:
+        return None
+
+    def preprocess(image: Any, scale: float = _OCR_SCALE) -> Any:
+        image = cv2.resize(image, None, fx=scale, fy=scale, interpolation=cv2.INTER_CUBIC)
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+        gray = cv2.medianBlur(gray, 3)
+        return cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)[1]
+
+    def ocr_extract(image: Any) -> Optional[ReceiverResult]:
+        data = pytesseract.image_to_data(
+            preprocess(image),
+            lang=lang,
+            config="--psm 6",
+            output_type=Output.DICT,
+        )
+        lines = {}  # type: Dict[Tuple[int, int, int], List[int]]
+        for idx, text in enumerate(data["text"]):
+            text = text.strip()
+            if not text or parse_confidence(data["conf"][idx]) < _MIN_CONFIDENCE:
+                continue
+            key = (data["block_num"][idx], data["par_num"][idx], data["line_num"][idx])
+            lines.setdefault(key, []).append(idx)
+
+        anchor = None  # type: Optional[Tuple[int, int, str]]
+        for _key, indexes in sorted(lines.items()):
+            line_text = " ".join(data["text"][idx].strip() for idx in indexes).strip()
+            if _ANCHOR_RE.search(line_text):
+                x1 = min(int(data["left"][idx] / _OCR_SCALE) for idx in indexes)
+                y1 = min(int(data["top"][idx] / _OCR_SCALE) for idx in indexes)
+                anchor = (x1, y1, line_text)
+                break
+
+        if not anchor:
+            return None
+
+        anchor_x, anchor_y, _anchor_text = anchor
+        height, width = image.shape[:2]
+        crop = image[
+            max(0, anchor_y - 10) : min(height, anchor_y + int(height * 0.25)),
+            max(0, anchor_x - 10) : min(width, int(width * 0.98)),
+        ]
+        raw = pytesseract.image_to_string(
+            preprocess(crop, scale=3.0),
+            lang=lang,
+            config="--psm 6",
+        )
+
+        output = []
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            line = _ANCHOR_PREFIX_RE.sub("", line).strip()
+            if not line:
+                continue
+            if is_stop(line):
+                break
+            output.append(line)
+
+        if not output:
+            return None
+        return {"name": output[0], "address": "\n".join(output[1:]), "strategy": "ocr"}
+
+    for image in load_images_for_ocr(file_path):
+        result = ocr_extract(image)
+        if result:
+            return result
+    return None

onflow_awb_ocr-0.1.0/onflow_awb_ocr/postprocess.py

@@ -0,0 +1,39 @@
+"""Result post-processing."""
+
+import re
+from typing import Iterable, List, Optional, Pattern
+
+from .types import ReceiverResult
+
+_NOISE_PATTERNS = (
+    re.compile(r"^[A-Za-z]{0,6}\d{6,}[A-Za-z]{0,3}$"),
+    re.compile(r"^[A-Z]{2,4}(\s+\d{1,4})?$"),
+    re.compile(r"^[A-Za-z0-9]+-[A-Za-z0-9]+-?[A-Za-z0-9]*$"),
+    re.compile(r"^\d{3,4}$"),
+)
+
+
+def is_noise_line(line: str, patterns: Iterable[Pattern[str]] = _NOISE_PATTERNS) -> bool:
+    if len(line) <= 2 or line == "-":
+        return True
+    return any(pattern.match(line) for pattern in patterns)
+
+
+def clean_address_lines(lines: List[str]) -> List[str]:
+    """Remove obvious airway bill, barcode, route, and layout noise lines."""
+    cleaned = []
+    for line in lines:
+        line = line.strip()
+        if not line or is_noise_line(line):
+            continue
+        cleaned.append(line)
+    return cleaned
+
+
+def post_process(result: Optional[ReceiverResult]) -> Optional[ReceiverResult]:
+    if not result:
+        return result
+    processed = dict(result)
+    address_lines = processed.get("address", "").splitlines()
+    processed["address"] = "\n".join(clean_address_lines(address_lines))
+    return processed

onflow_awb_ocr-0.1.0/onflow_awb_ocr/py.typed

@@ -0,0 +1 @@
+

onflow_awb_ocr-0.1.0/onflow_awb_ocr/receiver.py

@@ -0,0 +1,13 @@
+"""Compatibility exports for receiver extraction."""
+
+from .extractor import OnflowAwbOcr, ReceiverExtractor
+from .types import FileInput, ReceiverResult
+from .utils import format_result
+
+__all__ = [
+    "FileInput",
+    "OnflowAwbOcr",
+    "ReceiverExtractor",
+    "ReceiverResult",
+    "format_result",
+]

onflow_awb_ocr-0.1.0/onflow_awb_ocr/text_layer.py

@@ -0,0 +1,209 @@
+"""PDF text-layer receiver extraction strategies."""
+
+import re
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from .types import ReceiverResult, Span
+from .utils import is_stop
+
+
+_RE_NR_INLINE = re.compile(
+    r"(?:Ng[uư][ờơ]i|Nguoi)\s*nh[ậa]n\s*[:\-]?\s*(.+)",
+    re.IGNORECASE,
+)
+_RE_DEN = re.compile(r"^(?:Đ[eế]n|Den)\s*:?\s*$", re.IGNORECASE)
+_RE_DEN_INLINE = re.compile(r"(?:Đ[eế]n|Den)\s*:\s*", re.IGNORECASE)
+_RE_TU = re.compile(r"^(?:T[uừ]|Tu)\s*:?\s*$", re.IGNORECASE)
+_RE_NR_LABEL = re.compile(r"(?:Ng[uư][ờơ]i|Nguoi)\s*nh[ậa]n", re.IGNORECASE)
+_RE_SENDER_LABEL = re.compile(r"(?:Ng[uư][ờơ]i|Nguoi)\s*g[uư][ửừ]i", re.IGNORECASE)
+_Strategy = Tuple[str, Callable[[List[Span]], Optional[ReceiverResult]]]
+
+
+def get_spans(page: Any) -> List[Span]:
+    """Return sorted text spans as (y, x, size, text)."""
+    spans = []
+    for block in page.get_text("dict")["blocks"]:
+        if block["type"] != 0:
+            continue
+        for line in block["lines"]:
+            if not line["spans"]:
+                continue
+            y = round(line["spans"][0]["origin"][1], 0)
+            x = min(span["origin"][0] for span in line["spans"])
+            size = line["spans"][0]["size"]
+            text = "".join(span["text"] for span in line["spans"]).strip()
+            if text:
+                spans.append((y, round(x, 0), round(size, 1), text))
+    spans.sort(key=lambda span: (span[0], span[1]))
+    return spans
+
+
+def extract_lex(spans: List[Span]) -> Optional[ReceiverResult]:
+    """LEX / Lazada Logistics: "Người nhận: <Tên>" inline."""
+    anchor_idx = None
+    name = ""
+    for idx, (_y, _x, _size, text) in enumerate(spans):
+        match = _RE_NR_INLINE.match(text.strip())
+        if match:
+            name = match.group(1).strip()
+            if name:
+                anchor_idx = idx
+                break
+
+    if anchor_idx is None:
+        return None
+
+    lines = [name]
+    for _y, _x, _size, text in spans[anchor_idx + 1 :]:
+        value = text.strip()
+        if not value:
+            continue
+        if _RE_SENDER_LABEL.match(value) or is_stop(value):
+            break
+        lines.append(value)
+
+    return {"name": lines[0], "address": "\n".join(lines[1:]) if len(lines) > 1 else ""}
+
+
+def extract_shopee(spans: List[Span]) -> Optional[ReceiverResult]:
+    """Shopee SPX / Ahamove: right column below "Đến:"."""
+    den_y = None
+    den_x = None
+
+    for y, x, _size, text in spans:
+        stripped = text.strip()
+        if _RE_DEN.match(stripped):
+            den_y = y
+            den_x = x
+            break
+
+        if _RE_DEN_INLINE.match(stripped):
+            after = _RE_DEN_INLINE.sub("", text, count=1).strip()
+            if after:
+                den_y = y
+                den_x = x
+                lines = [after]
+                for y2, x2, _size2, text2 in spans:
+                    if y2 <= den_y:
+                        continue
+                    if x2 < den_x - 10:
+                        if is_stop(text2):
+                            break
+                        continue
+                    if is_stop(text2):
+                        break
+                    lines.append(text2.strip())
+                if lines:
+                    return {"name": lines[0], "address": "\n".join(lines[1:])}
+
+    if den_y is None or den_x is None:
+        return None
+
+    right_lines = {}  # type: Dict[float, List[str]]
+    stop_y = float("inf")
+    for y, x, _size, text in spans:
+        if y <= den_y:
+            continue
+        if x < den_x - 5:
+            if is_stop(text):
+                stop_y = min(stop_y, y)
+            continue
+        if y >= stop_y:
+            break
+        if is_stop(text):
+            stop_y = min(stop_y, y)
+            break
+        if _RE_DEN.match(text.strip()) or _RE_TU.match(text.strip()):
+            continue
+        right_lines.setdefault(y, []).append(text.strip())
+
+    lines = []
+    for y in sorted(right_lines):
+        merged = " ".join(right_lines[y]).strip()
+        if merged:
+            lines.append(merged)
+
+    if not lines:
+        return None
+    return {"name": lines[0], "address": "\n".join(lines[1:])}
+
+
+def extract_jt_vtp(spans: List[Span]) -> Optional[ReceiverResult]:
+    """J&T / Viettel Post: small "Người nhận" label, larger name/address below."""
+    anchor_idx = None
+    for idx, (_y, _x, size, text) in enumerate(spans):
+        if _RE_NR_LABEL.search(text.strip()) and size < 9:
+            anchor_idx = idx
+            break
+
+    if anchor_idx is None:
+        return None
+
+    anchor_y = spans[anchor_idx][0]
+    anchor_x = spans[anchor_idx][1]
+
+    name = ""
+    name_y = None
+    for y, x, size, text in spans[anchor_idx + 1 :]:
+        value = text.strip()
+        if not value:
+            continue
+        if is_stop(value):
+            break
+        if abs(y - anchor_y) < 5 and x > anchor_x:
+            name = value
+            name_y = y
+            break
+        if y > anchor_y and size > 8:
+            name = value
+            name_y = y
+            break
+        break
+
+    if not name:
+        return None
+
+    address_lines = []
+    for y, _x, _size, text in spans:
+        if name_y is None or y <= name_y:
+            continue
+        value = text.strip()
+        if not value:
+            continue
+        if is_stop(value):
+            break
+        if re.match(r"^\(\+\d+\)|^0\d+\*+", value):
+            continue
+        address_lines.append(value)
+
+    return {"name": name, "address": "\n".join(address_lines)}
+
+
+def extract_from_text_layer(pdf_path: str) -> Optional[ReceiverResult]:
+    try:
+        import fitz
+    except ImportError as exc:
+        raise RuntimeError("PyMuPDF is required to read PDF text layers.") from exc
+
+    doc = fitz.open(pdf_path)
+    try:
+        page = doc[0]
+        spans = get_spans(page)
+    finally:
+        doc.close()
+
+    if not spans:
+        return None
+
+    strategies = (  # type: Tuple[_Strategy, ...]
+        ("lex", extract_lex),
+        ("shopee", extract_shopee),
+        ("jt_vtp", extract_jt_vtp),
+    )
+    for strategy_name, strategy in strategies:
+        result = strategy(spans)
+        if result and result["name"]:
+            result["strategy"] = strategy_name
+            return result
+
+    return None

onflow_awb_ocr-0.1.0/onflow_awb_ocr/types.py

@@ -0,0 +1,9 @@
+"""Shared type aliases for the SDK."""
+
+from pathlib import Path
+from typing import BinaryIO, Dict, Tuple, Union
+
+
+ReceiverResult = Dict[str, str]
+FileInput = Union[str, Path, bytes, bytearray, BinaryIO]
+Span = Tuple[float, float, float, str]

onflow_awb_ocr-0.1.0/onflow_awb_ocr/utils.py

@@ -0,0 +1,45 @@
+"""Shared text helpers."""
+
+import re
+import unicodedata
+from typing import Iterable, Optional
+
+from .constants import STOP_KEYWORDS
+from .types import ReceiverResult
+
+_SAFE_TEXT_RE = re.compile(r"[^a-z0-9\s:/.-]")
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+def normalize(text: str) -> str:
+    normalized = unicodedata.normalize("NFKD", text.strip().lower())
+    without_marks = "".join(char for char in normalized if not unicodedata.combining(char))
+    safe_text = _SAFE_TEXT_RE.sub(" ", without_marks)
+    return _WHITESPACE_RE.sub(" ", safe_text).strip()
+
+
+def _normalize_all(values: Iterable[str]) -> tuple:
+    return tuple(normalize(value) for value in values)
+
+
+_NORMALIZED_STOP_KEYWORDS = _normalize_all(STOP_KEYWORDS)
+
+
+def is_stop(line: str) -> bool:
+    norm = normalize(line)
+    return any(keyword in norm for keyword in _NORMALIZED_STOP_KEYWORDS)
+
+
+def is_url(value: str) -> bool:
+    return value.startswith("http://") or value.startswith("https://")
+
+
+def format_result(result: Optional[ReceiverResult]) -> str:
+    if not result:
+        return "Không tìm thấy thông tin receiver."
+
+    parts = [result.get("name", "")]
+    address = result.get("address", "").strip()
+    if address:
+        parts.append(address)
+    return "\n".join(part for part in parts if part)

onflow_awb_ocr-0.1.0/onflow_awb_ocr.egg-info/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: onflow-awb-ocr
+Version: 0.1.0
+Summary: Python SDK for extracting receiver information from AWB/shipping labels.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: PyMuPDF>=1.20
+Requires-Dist: requests>=2.25
+Provides-Extra: ocr
+Requires-Dist: opencv-python>=4.5; extra == "ocr"
+Requires-Dist: pytesseract>=0.3; extra == "ocr"
+Requires-Dist: numpy>=1.21; extra == "ocr"
+
+# Onflow AWB OCR
+
+Python SDK for extracting receiver information from AWB and shipping label files.
+
+The package supports PDF files with a text layer first, then falls back to OCR for
+scanned PDFs and image files when OCR dependencies are installed.
+
+## Requirements
+
+- Python 3.8+
+- PyMuPDF for PDF text-layer extraction
+- Optional OCR stack for scanned files and images:
+  - Tesseract OCR
+  - Vietnamese Tesseract language data
+  - Poppler `pdftoppm`
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install onflow-awb-ocr
+```
+
+Install with OCR dependencies:
+
+```bash
+pip install "onflow-awb-ocr[ocr]"
+```
+
+On Ubuntu, install the native OCR tools:
+
+```bash
+sudo apt install -y tesseract-ocr tesseract-ocr-vie poppler-utils
+```
+
+For local development:
+
+```bash
+pip install -e ".[ocr]"
+```
+
+## Usage
+
+```python
+from onflow_awb_ocr import OnflowAwbOcr
+
+ocr = OnflowAwbOcr(lang="vie+eng")
+result = ocr.extract("label.pdf")
+
+print(result)
+```
+
+Example result:
+
+```python
+{
+    "name": "Nguyen Van A",
+    "address": "123 Nguyen Trai\nQuan 1, TP. Ho Chi Minh",
+    "strategy": "shopee",
+}
+```
+
+If no receiver can be detected, `extract()` returns `None`.
+
+## Supported Inputs
+
+`extract()` accepts:
+
+- Local file path as `str`
+- Local file path as `pathlib.Path`
+- HTTP/HTTPS URL
+- `bytes`
+- `bytearray`
+- Binary file-like object
+
+Examples:
+
+```python
+from pathlib import Path
+
+from onflow_awb_ocr import OnflowAwbOcr
+
+ocr = OnflowAwbOcr()
+
+from_path = ocr.extract(Path("label.pdf"))
+from_url = ocr.extract("https://example.com/label.pdf")
+
+with open("label.pdf", "rb") as file:
+    from_file = ocr.extract(file)
+
+with open("label.png", "rb") as file:
+    from_bytes = ocr.extract(file.read())
+```
+
+## Compatibility
+
+The old `ReceiverExtractor` class name is still available as an alias:
+
+```python
+from onflow_awb_ocr import ReceiverExtractor
+
+ocr = ReceiverExtractor()
+result = ocr.extract("label.pdf")
+```
+
+## Package Structure
+
+- `extractor.py`: public `OnflowAwbOcr` class
+- `input.py`: input preparation for paths, URLs, bytes, and binary streams
+- `text_layer.py`: PDF text-layer extraction strategies
+- `ocr.py`: OCR fallback for scanned PDFs and images
+- `postprocess.py`: address cleanup
+- `types.py`, `constants.py`, `utils.py`: shared types, constants, and helpers
+
+## Publishing
+
+GitHub Actions builds and publishes the package to PyPI on every push to `main`.
+
+The repository must define this GitHub secret:
+
+```text
+PYPI_API_TOKEN
+```
+
+PyPI does not allow replacing an existing version. If a commit on `main` does not
+bump `project.version` in `pyproject.toml`, the publish step skips the existing
+distribution.

onflow_awb_ocr-0.1.0/onflow_awb_ocr.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+onflow_awb_ocr/__init__.py
+onflow_awb_ocr/constants.py
+onflow_awb_ocr/extractor.py
+onflow_awb_ocr/input.py
+onflow_awb_ocr/ocr.py
+onflow_awb_ocr/postprocess.py
+onflow_awb_ocr/py.typed
+onflow_awb_ocr/receiver.py
+onflow_awb_ocr/text_layer.py
+onflow_awb_ocr/types.py
+onflow_awb_ocr/utils.py
+onflow_awb_ocr.egg-info/PKG-INFO
+onflow_awb_ocr.egg-info/SOURCES.txt
+onflow_awb_ocr.egg-info/dependency_links.txt
+onflow_awb_ocr.egg-info/requires.txt
+onflow_awb_ocr.egg-info/top_level.txt

onflow_awb_ocr-0.1.0/onflow_awb_ocr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

onflow_awb_ocr-0.1.0/onflow_awb_ocr.egg-info/requires.txt

@@ -0,0 +1,7 @@
+PyMuPDF>=1.20
+requests>=2.25
+
+[ocr]
+opencv-python>=4.5
+pytesseract>=0.3
+numpy>=1.21

onflow_awb_ocr-0.1.0/onflow_awb_ocr.egg-info/top_level.txt

@@ -0,0 +1 @@
+onflow_awb_ocr

onflow_awb_ocr-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "onflow-awb-ocr"
+version = "0.1.0"
+description = "Python SDK for extracting receiver information from AWB/shipping labels."
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "PyMuPDF>=1.20",
+    "requests>=2.25",
+]
+
+[project.optional-dependencies]
+ocr = [
+    "opencv-python>=4.5",
+    "pytesseract>=0.3",
+    "numpy>=1.21",
+]
+
+[tool.setuptools.packages.find]
+include = ["onflow_awb_ocr*"]
+
+[tool.setuptools.package-data]
+onflow_awb_ocr = ["py.typed"]

onflow_awb_ocr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+