structverify 0.3.0__py3-none-any.whl

structverify/preprocessing/pdf/markdown.py

@@ -0,0 +1,107 @@
+"""
+preprocessing/pdf/markdown.py — Markdown 직렬화 + OCR 인라인 병합
+
+* `to_markdown`                    : Extracted → 최종 MD 문자열
+* `table_to_md`                    : BeautifulSoup `<table>` → MD 표
+* `inline_image_ocr_into_body`     : 이미지 OCR 결과를 본문 페이지 앵커 뒤에 삽입
+* `append_scanned_ocr`             : 스캔 페이지 OCR 을 body 에 병합 (교체/추가)
+"""
+from __future__ import annotations
+
+from structverify.preprocessing.pdf.models import (
+    Extracted, ImageOcrHit, PageText)
+
+
+def table_to_md(tbl) -> str:
+    """BeautifulSoup `<table>` 엘리먼트를 Markdown 표로 변환."""
+    rows: list[list[str]] = []
+    for tr in tbl.find_all("tr"):
+        cells = [c.get_text(" ", strip=True) for c in tr.find_all(["th", "td"])]
+        if cells:
+            rows.append(cells)
+    if not rows:
+        return ""
+    width = max(len(r) for r in rows)
+    rows = [r + [""] * (width - len(r)) for r in rows]
+    md = ["| " + " | ".join(rows[0]) + " |",
+          "| " + " | ".join(["---"] * width) + " |"]
+    for r in rows[1:]:
+        md.append("| " + " | ".join(r) + " |")
+    return "\n".join(md)
+
+
+def inline_image_ocr_into_body(body: str,
+                               image_ocr: dict[int, list[ImageOcrHit]],
+                               pages: list[PageText]) -> str:
+    """
+    본문에 이미지 OCR 결과 삽입.
+    전략:
+      1) 각 페이지의 PyMuPDF 텍스트 첫 유의미한 라인(10자+) 을 앵커로 검색
+      2) 앵커 직후 단락 경계에 `> **[이미지 p.N-k]** <OCR>` 인용 블록 삽입
+      3) 앵커 매칭 실패 시 body 말미 `## 이미지 내 텍스트` 섹션으로 폴백
+    """
+    if not image_ocr:
+        return body
+
+    def block(pno: int) -> str:
+        lines = []
+        for hit in image_ocr[pno]:
+            snippet = hit.text.strip()
+            if snippet:
+                quoted = snippet.replace("\n", "\n> ")
+                lines.append(
+                    f"\n> **[이미지 p.{pno+1}-{hit.idx+1}]**\n>\n> {quoted}"
+                )
+        return "\n".join(lines)
+
+    merged = body
+    orphans: list[tuple[int, str]] = []
+    for pno in sorted(image_ocr):
+        page_text = next((p.text for p in pages if p.page_no == pno), "").strip()
+        anchor = next(
+            (l.strip()[:30] for l in page_text.splitlines() if len(l.strip()) >= 10),
+            "",
+        )
+        if anchor and anchor in merged:
+            idx = merged.find(anchor) + len(anchor)
+            nl = merged.find("\n\n", idx)
+            insert_at = nl if nl != -1 else len(merged)
+            merged = merged[:insert_at] + "\n\n" + block(pno) + merged[insert_at:]
+        else:
+            orphans.append((pno, block(pno)))
+
+    if orphans:
+        merged += "\n\n## 이미지 내 텍스트\n"
+        for pno, blk in orphans:
+            merged += f"\n**p.{pno+1}**\n{blk}\n"
+    return merged
+
+
+def append_scanned_ocr(body: str, scanned_ocr: dict[int, str],
+                       total_pages: int) -> str:
+    """
+    스캔 페이지 OCR 병합.
+    * 전체 페이지의 50%↑ 가 스캔이면 body 전체를 OCR 결과로 교체
+      (텍스트 레이어가 없는 문서이므로 Docling body 는 신뢰 불가)
+    * 미만이면 말미 `## 스캔 페이지 OCR` 섹션으로 append
+    """
+    if not scanned_ocr:
+        return body
+    if len(scanned_ocr) * 2 >= max(total_pages, 1):
+        return "\n\n".join(scanned_ocr[k] for k in sorted(scanned_ocr))
+    out = body + "\n\n## 스캔 페이지 OCR\n"
+    for pno in sorted(scanned_ocr):
+        out += f"\n**p.{pno+1}**\n\n{scanned_ocr[pno]}\n"
+    return out
+
+
+def to_markdown(ex: Extracted) -> str:
+    """Extracted → 최종 Markdown 문자열."""
+    parts: list[str] = []
+    if ex.title:
+        parts.append(f"# {ex.title.strip()}")
+    if ex.date:
+        parts.append(f"_작성일: {ex.date.strip()}_")
+    parts.append("")
+    parts.append(ex.body.strip())
+    return "\n\n".join(parts).strip() + "\n"

structverify/preprocessing/pdf/models.py

@@ -0,0 +1,34 @@
+"""
+preprocessing/pdf/models.py — PDF 파이프라인 내부용 데이터 구조
+
+* 파이프라인 단계 사이 전달용이며, 외부 스키마(`core.schemas`)와는 분리.
+* SIR Tree 로의 변환은 상위 단계(`sir_builder.py`)에서 수행.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+@dataclass
+class PageText:
+    """PyMuPDF 로 추출한 페이지 단위 정보"""
+    page_no: int
+    text: str
+    needs_ocr: bool          # 텍스트 레이어가 비어있음 → 스캔 페이지
+    has_images: bool         # 이미지 블록 존재 → 이미지 OCR 대상
+
+
+@dataclass
+class Extracted:
+    """선택된 소스(JSON/HTML)에서 뽑은 필드"""
+    title: str = ""
+    date: str = ""
+    body: str = ""
+    source_used: str = ""    # "json" | "html" | "pymupdf"
+
+
+@dataclass
+class ImageOcrHit:
+    """이미지 블록 OCR 결과 단위"""
+    idx: int                 # 페이지 내 이미지 순번
+    bbox: tuple              # (x0, y0, x1, y1)
+    text: str

structverify/preprocessing/pdf/ocr.py

@@ -0,0 +1,172 @@
+"""
+preprocessing/pdf/ocr.py — OCR 백엔드 라우팅 + 이미지/스캔 OCR
+
+백엔드 비교 (한국어 기준 벤치마크):
+  * EasyOCR    : 한글 정확도 가장 우수, 초기 모델 로드 느림 → 싱글톤
+  * Tesseract  : 빠르지만 한글 정확도 약함 (영문 위주 문서에만 추천)
+  * PaddleOCR  : 정확도·속도 절충, 한국어 모델 별도 설치 필요
+
+환경변수 `OCR_BACKEND` (기본: easyocr) 로 교체.
+실제 라이브러리는 지연 로드 — 설치돼 있지 않으면 해당 백엔드만 실패하고
+다른 백엔드/파이프라인 단계는 정상 동작.
+"""
+from __future__ import annotations
+import io
+import os
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+try:
+    from PIL import Image
+except ImportError:
+    Image = None  # type: ignore
+
+from structverify.preprocessing.pdf.models import PageText, ImageOcrHit
+from structverify.preprocessing.pdf.reader import (
+    get_image_rects, render_region_png)
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+DEFAULT_BACKEND = "easyocr"
+
+# 리더 싱글톤 (모델 재로딩 비용 방지)
+_easy_reader = None
+_paddle_reader = None
+
+
+# ── 백엔드 함수 ─────────────────────────────────────────────────────────
+
+def _ocr_easyocr(img) -> str:
+    global _easy_reader
+    import easyocr  # type: ignore
+    import numpy as np
+    if _easy_reader is None:
+        _easy_reader = easyocr.Reader(["ko", "en"], gpu=False)
+    return "\n".join(_easy_reader.readtext(np.array(img), detail=0))
+
+
+def _ocr_tesseract(img) -> str:
+    import pytesseract  # type: ignore
+    return pytesseract.image_to_string(img, lang="kor+eng")
+
+
+def _ocr_paddle(img) -> str:
+    global _paddle_reader
+    from paddleocr import PaddleOCR  # type: ignore
+    import numpy as np
+    if _paddle_reader is None:
+        _paddle_reader = PaddleOCR(
+            use_angle_cls=True, lang="korean", show_log=False)
+    res = _paddle_reader.ocr(np.array(img), cls=True)
+    out: list[str] = []
+    for block in res or []:
+        for line in block or []:
+            if line and len(line) >= 2 and line[1]:
+                out.append(line[1][0])
+    return "\n".join(out)
+
+
+_BACKENDS = {
+    "easyocr": _ocr_easyocr,
+    "tesseract": _ocr_tesseract,
+    "paddleocr": _ocr_paddle,
+}
+
+
+def resolve_backend(backend: str | None = None) -> str:
+    b = backend or os.environ.get("OCR_BACKEND", DEFAULT_BACKEND)
+    if b not in _BACKENDS:
+        raise ValueError(f"unknown OCR backend: {b}")
+    return b
+
+
+def run_ocr(img, backend: str | None = None) -> str:
+    return _BACKENDS[resolve_backend(backend)](img)
+
+
+def benchmark(img, backends=("tesseract", "easyocr")) -> dict:
+    """개발용 벤치 — 백엔드별 처리시간/글자수/샘플 비교."""
+    import time
+    report: dict = {}
+    for name in backends:
+        fn = _BACKENDS[name]
+        t0 = time.time()
+        try:
+            out = fn(img)
+            report[name] = {
+                "ok": True,
+                "elapsed": round(time.time() - t0, 2),
+                "chars": len(out),
+                "sample": out[:160],
+            }
+        except Exception as e:
+            report[name] = {"ok": False,
+                            "error": f"{type(e).__name__}: {e}"}
+    return report
+
+
+# ── 이미지 블록 crop OCR ────────────────────────────────────────────────
+
+def _open_png(png_bytes: bytes):
+    if Image is None:
+        raise RuntimeError("Pillow 미설치 - OCR 불가")
+    return Image.open(io.BytesIO(png_bytes))
+
+
+def ocr_page_images(pdf_path: str, page_no: int,
+                    backend: str | None = None) -> list[ImageOcrHit]:
+    """페이지 내 이미지 블록 각각에 대해 crop → OCR."""
+    hits: list[ImageOcrHit] = []
+    for i, bb in enumerate(get_image_rects(pdf_path, page_no)):
+        # 아이콘/로고(30pt 미만) 는 OCR 가치 낮음 → skip
+        if (bb[2] - bb[0] < 30) or (bb[3] - bb[1] < 30):
+            continue
+        try:
+            png = render_region_png(pdf_path, page_no, bb, dpi=300)
+            text = run_ocr(_open_png(png), backend).strip()
+        except Exception as e:
+            logger.warning(f"image OCR 실패 p{page_no} #{i}: {e}")
+            continue
+        if text:
+            hits.append(ImageOcrHit(idx=i, bbox=bb, text=text))
+    return hits
+
+
+def collect_image_ocr(pdf_path: str, pages: list[PageText],
+                      backend: str | None = None,
+                      max_workers: int = 4) -> dict[int, list[ImageOcrHit]]:
+    """이미지 포함 페이지만 Thread 병렬. 결과 {page_no: [ImageOcrHit...]}"""
+    targets = [p.page_no for p in pages if p.has_images]
+    if not targets:
+        return {}
+    out: dict[int, list[ImageOcrHit]] = {}
+    with ThreadPoolExecutor(max_workers=max_workers) as ex:
+        fut = {ex.submit(ocr_page_images, pdf_path, pno, backend): pno
+               for pno in targets}
+        for f in as_completed(fut):
+            res = f.result()
+            if res:
+                out[fut[f]] = res
+    return out
+
+
+# ── 스캔 페이지 전체 OCR ────────────────────────────────────────────────
+
+def collect_scanned_ocr(pdf_path: str, pages: list[PageText],
+                        backend: str | None = None,
+                        max_workers: int = 4) -> dict[int, str]:
+    """`needs_ocr=True` 페이지를 full-page 렌더 → OCR."""
+    targets = [p.page_no for p in pages if p.needs_ocr]
+    if not targets or Image is None:
+        return {}
+
+    def _full(pno: int) -> str:
+        png = render_region_png(pdf_path, pno, bbox=None, dpi=220)
+        return run_ocr(_open_png(png), backend)
+
+    out: dict[int, str] = {}
+    with ThreadPoolExecutor(max_workers=max_workers) as ex:
+        fut = {ex.submit(_full, pno): pno for pno in targets}
+        for f in as_completed(fut):
+            out[fut[f]] = f.result()
+    return out

structverify/preprocessing/pdf/pipeline.py

@@ -0,0 +1,74 @@
+"""
+preprocessing/pdf/pipeline.py — PDF → Markdown 오케스트레이터
+
+단계:
+  1) PyMuPDF 페이지 병렬 추출 (`reader.extract_all_pages`)
+  2) Docling JSON+HTML 추출 (`reader.docling_extract`)
+  3) 소스 스코어링 → 선택 (`scoring.pick_source`)
+  4) 선택 소스에서 title/date/body 추출 + 평문 정규식 폴백 (`fields`)
+  5) 이미지 블록 crop OCR 후 본문 인라인 삽입 (`ocr` + `markdown`)
+  6) 스캔 페이지 전체 OCR 후 body 교체/추가 (`ocr` + `markdown`)
+  7) Markdown 직렬화 (`markdown.to_markdown`)
+
+실패에 관대하게: Docling/OCR 어느 단계가 고장나도 가능한 결과를 반환.
+"""
+from __future__ import annotations
+
+from structverify.preprocessing.pdf.models import Extracted
+from structverify.preprocessing.pdf import reader, scoring, fields, ocr, markdown
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def extract_pdf_to_markdown(filepath: str,
+                            ocr_backend: str | None = None) -> str:
+    """PDF 파일 경로 → Markdown 문자열. 공개 API."""
+    pdf_path = str(filepath)
+
+    # 1) 페이지 텍스트
+    try:
+        pages = reader.extract_all_pages(pdf_path)
+    except Exception as e:
+        logger.error(f"PDF 열기 실패: {pdf_path} — {e}")
+        return ""
+    plain = "\n\n".join(p.text for p in pages)
+
+    # 2~3) 구조화 추출 + 소스 선택
+    dl = reader.docling_extract(pdf_path)
+    if dl["ok"]:
+        src = scoring.pick_source(dl)
+        ex = (fields.extract_from_json(dl["json"]) if src == "json"
+              else fields.extract_from_html(dl["html"]))
+    else:
+        ex = Extracted(body=plain, source_used="pymupdf")
+
+    # 4) 필드 폴백
+    if not ex.title:
+        ex.title = fields.fallback_from_plain(plain, "title")
+    if not ex.date:
+        ex.date = fields.fallback_from_plain(plain, "date")
+    if len(ex.body) < 50:
+        ex.body = plain
+
+    # 5) 이미지 블록 crop OCR → 본문 인라인
+    try:
+        image_ocr = ocr.collect_image_ocr(pdf_path, pages, ocr_backend)
+    except Exception as e:
+        logger.warning(f"이미지 OCR 단계 스킵: {e}")
+        image_ocr = {}
+    if image_ocr:
+        ex.body = markdown.inline_image_ocr_into_body(ex.body, image_ocr, pages)
+
+    # 6) 스캔 페이지 전체 OCR → body 교체/추가
+    try:
+        scanned_ocr = ocr.collect_scanned_ocr(pdf_path, pages, ocr_backend)
+    except Exception as e:
+        logger.warning(f"스캔 OCR 단계 스킵: {e}")
+        scanned_ocr = {}
+    if scanned_ocr:
+        ex.body = markdown.append_scanned_ocr(
+            ex.body, scanned_ocr, total_pages=len(pages))
+
+    # 7) Markdown 직렬화
+    return markdown.to_markdown(ex)

structverify/preprocessing/pdf/reader.py

@@ -0,0 +1,119 @@
+"""
+preprocessing/pdf/reader.py — PyMuPDF & Docling 기반 1차 추출
+
+* PyMuPDF: 페이지 텍스트 레이어 + 이미지 bbox + 고해상도 crop 렌더링
+* Docling: JSON + HTML 동시 export (소스 스코어링에 사용)
+"""
+from __future__ import annotations
+import os
+from concurrent.futures import ProcessPoolExecutor, as_completed
+
+# PyMuPDF (fitz) is optional and AGPL-3.0 licensed — it powers only this advanced
+# OCR / image-rendering PDF pipeline, never the core library. Import lazily so the
+# package installs and imports cleanly without it; callers that actually use this
+# module get a clear install hint. (The core PDF path uses pdfplumber, MIT.)
+try:
+    import fitz  # PyMuPDF
+except ImportError:  # pragma: no cover
+    fitz = None
+
+from structverify.preprocessing.pdf.models import PageText
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _require_fitz():
+    if fitz is None:
+        raise ImportError(
+            "This PDF feature needs PyMuPDF. Install it with "
+            "`pip install \"structverify[pdf-ocr]\"` (note: PyMuPDF is AGPL-3.0)."
+        )
+    return fitz
+
+
+# ── PyMuPDF 페이지 텍스트 ────────────────────────────────────────────────
+
+def extract_page(pdf_path: str, page_no: int) -> PageText:
+    """단일 페이지 PyMuPDF 추출. 프로세스 병렬에서도 동작하도록 순수 함수."""
+    _require_fitz()
+    with fitz.open(pdf_path) as doc:
+        page = doc[page_no]
+        txt = page.get_text("text") or ""
+        images = page.get_images(full=True)
+    return PageText(
+        page_no=page_no,
+        text=txt,
+        needs_ocr=len(txt.strip()) < 20,
+        has_images=len(images) > 0,
+    )
+
+
+def extract_all_pages(pdf_path: str) -> list[PageText]:
+    """페이지 단위 병렬 추출. 페이지 수 2 이하는 순차(오버헤드 방지)."""
+    _require_fitz()
+    with fitz.open(pdf_path) as doc:
+        n = doc.page_count
+    if n <= 2:
+        return [extract_page(pdf_path, i) for i in range(n)]
+    workers = min(os.cpu_count() or 4, n)
+    with ProcessPoolExecutor(max_workers=workers) as ex:
+        fut = {ex.submit(extract_page, pdf_path, i): i for i in range(n)}
+        pages = [f.result() for f in as_completed(fut)]
+    return sorted(pages, key=lambda p: p.page_no)
+
+
+# ── PyMuPDF 이미지 bbox ──────────────────────────────────────────────────
+
+def get_image_rects(pdf_path: str, page_no: int) -> list[tuple]:
+    """페이지의 이미지 xref bbox 목록 (중복 xref 제거)."""
+    _require_fitz()
+    rects: list[tuple] = []
+    with fitz.open(pdf_path) as doc:
+        page = doc[page_no]
+        seen: set = set()
+        for info in page.get_images(full=True):
+            xref = info[0]
+            if xref in seen:
+                continue
+            seen.add(xref)
+            try:
+                for r in page.get_image_rects(xref):
+                    rects.append((float(r.x0), float(r.y0),
+                                  float(r.x1), float(r.y1)))
+            except Exception:
+                continue
+    return rects
+
+
+def render_region_png(pdf_path: str, page_no: int, bbox: tuple | None = None,
+                      dpi: int = 300) -> bytes:
+    """페이지 일부 또는 전체를 PNG 바이트로 렌더링. OCR 입력으로 사용."""
+    _require_fitz()
+    with fitz.open(pdf_path) as doc:
+        page = doc[page_no]
+        mat = fitz.Matrix(dpi / 72, dpi / 72)
+        pix = page.get_pixmap(matrix=mat, clip=fitz.Rect(*bbox)) \
+            if bbox else page.get_pixmap(matrix=mat)
+    return pix.tobytes("png")
+
+
+# ── Docling 구조화 추출 ──────────────────────────────────────────────────
+
+def docling_extract(pdf_path: str) -> dict:
+    """Docling 으로 JSON + HTML 동시 추출. 실패 시 비어있는 결과."""
+    try:
+        from docling.document_converter import DocumentConverter
+    except ImportError:
+        logger.warning("docling 미설치 - 구조화 추출 스킵")
+        return {"json": None, "html": None, "ok": False}
+    try:
+        doc = DocumentConverter().convert(pdf_path).document
+        return {
+            "json": doc.export_to_dict(),
+            "html": doc.export_to_html(),
+            "ok": True,
+        }
+    except Exception as e:
+        logger.warning(f"docling 변환 실패: {e}")
+        return {"json": None, "html": None, "ok": False}

structverify/preprocessing/pdf/scoring.py

@@ -0,0 +1,61 @@
+"""
+preprocessing/pdf/scoring.py — JSON vs HTML 소스 품질 스코어링
+
+Docling 이 둘 다 생성 가능하지만 문서별로 어느 쪽이 후속 필드 추출에
+유리한지 다르다. 간단한 휴리스틱으로 점수를 매겨 높은 쪽을 선택.
+"""
+from __future__ import annotations
+import json
+import re
+from typing import Literal
+
+try:
+    from bs4 import BeautifulSoup
+except ImportError:
+    BeautifulSoup = None  # type: ignore
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def score_json(j: dict | None) -> int:
+    if not j:
+        return -999
+    s = 0
+    flat = json.dumps(j, ensure_ascii=False)
+    if re.search(r'"(title|heading)"', flat):
+        s += 3
+    if re.search(r'"(date|published|created)"', flat, re.I):
+        s += 3
+    if len(re.findall(r'"text"\s*:\s*"([^"]{2,})"', flat)) >= 20:
+        s += 2
+    if re.search(r'"(cells?|rows?|columns?)"', flat):
+        s += 2
+    return s
+
+
+def score_html(h: str | None) -> int:
+    if not h or BeautifulSoup is None:
+        return -999
+    s = 0
+    soup = BeautifulSoup(h, "lxml")
+    if len(soup.find_all("table")) >= 3:
+        s += 2
+    tags = {t.name for t in soup.find_all(
+        ["h1", "h2", "h3", "p", "table", "ul", "ol"])}
+    if len(tags) >= 3:
+        s += 2
+    if soup.find(["h1", "h2"]):
+        s += 1
+    if soup.find(string=re.compile(r"\d{4}[-./]\d{1,2}[-./]\d{1,2}")):
+        s += 1
+    return s
+
+
+def pick_source(docling_result: dict) -> Literal["json", "html"]:
+    """둘 다 가능할 때 높은 점수. 동점 시 JSON (구조화 메타가 풍부한 경향)."""
+    sj = score_json(docling_result.get("json"))
+    sh = score_html(docling_result.get("html"))
+    logger.info(f"source score | json={sj} html={sh}")
+    return "json" if sj >= sh else "html"