ocr-postprocess 0.1.0

Biến raw OCR text thành structured document — trích xuất trường dữ liệu, xử lý nhiễu, cross-check, render JSON/Markdown.

ocr-postprocess

Biến raw OCR text thành structured document — trích xuất trường dữ liệu, xử lý nhiễu, cross-check, và render ra JSON/Markdown.

Installation

pip install ocr-postprocess

Hoặc cài từ source:

git clone https://github.com/your-org/ocr-postprocess
cd ocr-postprocess
pip install -e .

Library usage

from ocr_postprocess import Pipeline, ProcessedDocument, OcrPostprocessError

# Sử dụng profiles bundled sẵn (no extra files needed)
pipeline = Pipeline.from_default()

raw_text = open("scan.txt").read()

try:
    doc: ProcessedDocument = pipeline.process(raw_text)
except OcrPostprocessError as exc:
    print(f"Pipeline error: {exc}")
    raise

# Lấy một trường
name_candidate = doc.get("ho_va_ten")
if name_candidate:
    print(name_candidate.value)       # "NGUYỄN VĂN A"
    print(name_candidate.confidence)  # 0.91

# Toàn bộ trường đã trích
fields = {c.key: c.value for c in doc.candidates}

# Export JSON
import json
print(json.dumps(doc.to_json(), ensure_ascii=False, indent=2))

# Export Markdown
print(doc.markdown)

Custom profiles directory

# Dùng thư mục profiles riêng
pipeline = Pipeline.from_default(profiles_dir="my_profiles/")

Classify only

profile_id, score = pipeline.classify(raw_text)
# "cccd_2024", 0.97

ProcessedDocument fields

Field	Type	Mô tả
profile_id	str	Profile được match
profile_score	float	Điểm classify (0–1)
candidates	list[Candidate]	Tất cả trường đã trích
overall_confidence	float	Điểm tin cậy tổng hợp
warnings	list[str]	Cảnh báo từ pipeline
markdown	str	Kết quả render Markdown
cross_checks	list[CrossCheck]	Kết quả cross-check

CLI

# Process a document
ocrpp process scan.txt

# Markdown output
ocrpp process scan.txt --format markdown

# Classify only
ocrpp classify scan.txt

# Validate a profile
ocrpp validate-profile profiles/my_profile.yml

# Custom profiles directory
ocrpp process scan.txt --profiles ./my_profiles/

Adding a custom profile

Tạo file YAML trong thư mục profiles của bạn:

id: my_doc
version: 1
display_name: "My document type"

classify:
  any_of:
    - contains_any: ["MY DOCUMENT HEADER"]

extract:
  - name: document_number
    aliases: ["Document No", "Số chứng từ"]
    extractor: value_in_same_line
    required: true

Sau đó:

pipeline = Pipeline.from_default(profiles_dir="my_profiles/")

Exceptions

from ocr_postprocess import (
    OcrPostprocessError,      # base
    ProfileNotFoundError,
    ProfileValidationError,
    ExtractorNotFoundError,
    TransformError,
)

Development

python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
pip install -e .

pytest                    # all tests
pytest tests/unit         # unit only
pytest -m golden          # golden/regression
pytest -n auto --cov      # parallel + coverage
ruff check . && black --check .

Docs

Xem docs/README.md để biết chi tiết về pipeline stages và profile schema.