Skip to main content

jp-receipt-normalize

Python 3.10+ License: MIT Typing: Typed

日本語帳票OCRの監査可能な正規化・候補抽出ライブラリ

English README is available here (README_en.md) | 設計思想: なぜ曖昧なら直さないか (docs/design_principles.md)


概要

日本語の領収書・レシート・請求書をOCR処理すると、全角半角、Unicode字形、簡体字・異体字、記号の誤読、空白、桁区切りなどが揺れる場合があります。

しかし、業務自動化において「それらしく見える値へ勝手に直す」ことは、誤請求や税務申告ミスを引き起こす危険があります。

jp-receipt-normalize は、OCRエンジンやLLMを内包しない、OCR後段の処理を対象とした監査可能な部品です。 元の文字列、変更箇所、適用規則、曖昧性の理由を記録・保持したうえで、候補を抽出します。

特徴

  1. 監査可能性: 文字列の変更は Edit(rule, source, replacement, start, end) として記録され、元の位置と差分を追跡できます。
  2. 曖昧な補正を自動確定しない: 「O」と「0」、「l」と「1」、ピリオド桁区切り(¥1.840)など、文脈なしに断定できない曖昧な補正は自動確定せず、status="ambiguous" や判定理由(reasons)を返します。
  3. 日本語帳票向けの候補抽出:
    • 金額(負数・値引き・税額・通貨記号・桁区切り)
    • 日付(西暦・和暦・令和元年・実在日うるう年検証)
    • 時刻(24時間表記・時分秒・コロン揺れ)
    • 日本の電話番号(市外局番体系・固定・携帯・フリーダイヤル・IP電話・ハイフン除去)
    • 適格請求書発行事業者登録番号(T + 13桁・国税庁法人番号チェックデジット検証)
    • JAN/EANコード(8桁・13桁・モジュラス10ウェイト3チェックデジット検証)
  4. 外部通信なし・ゼロ依存: Python標準ライブラリ中心で動作します。外部API呼び出しやネットワーク通信は行わず、決定論的に動作します。
  5. JSON直列化と型付け: to_dict() によるJSON直列化と、py.typed による静的型チェック(mypy strict)に対応しています。

インストール

pip install jp-receipt-normalize

クイックスタート

from jpdoc_normalize import normalize_text
from jpdoc_normalize.fields import (
    find_amounts,
    find_dates,
    find_invoice_registration_numbers,
    find_phone_numbers,
)

# 1. 文字列の監査可能正規化
ocr_text = "合 計 ¥1,840"
normalized = normalize_text(ocr_text, profile="receipt")

print(normalized.text)
# => "合 計 ¥1,840"

# 変更履歴(Edit)の確認
for edit in normalized.edits:
    print(f"Rule: {edit.rule}, Source: {edit.source!r} -> {edit.replacement!r} [{edit.start}:{edit.end}]")
# => Rule: normalize_space, Source: ' ' -> ' ' [2:3]
# => Rule: fullwidth_digit_to_halfwidth, Source: '8' -> '8' [5:6]
# => Rule: fullwidth_digit_to_halfwidth, Source: '4' -> '4' [6:7]
# => Rule: fullwidth_digit_to_halfwidth, Source: '0' -> '0' [7:8]

# 2. 金額候補の抽出
amounts = find_amounts(normalized)
print(amounts[0].value, amounts[0].status, amounts[0].reasons)
# => 1840 normalized ('has_currency_symbol',)

# 3. インボイス登録番号の抽出と法人番号チェックデジット検証
registrations = find_invoice_registration_numbers("登録番号 T6120001018791")
for candidate in registrations:
    print(candidate.value, candidate.status, candidate.reasons)
# => T6120001018791 normalized ('has_registration_keyword', 'valid_corporate_number_checksum')

主要データ型

SourceSpan

元のOCR入力におけるテキストスパン、座標情報、信頼度を保持します。

@dataclass(frozen=True)
class SourceSpan:
    text: str
    start: int
    end: int
    page: int | None = None
    bbox: tuple[float, float, float, float] | None = None
    confidence: float | None = None
    engine: str | None = None

Edit

テキスト正規化における1つの編集操作。監査証跡として保存されます。

@dataclass(frozen=True)
class Edit:
    rule: str
    source: str
    replacement: str
    start: int
    end: int

Candidate[T]

抽出されたフィールドの候補値。判定ステータスと根拠理由を持ちます。

@dataclass(frozen=True)
class Candidate(Generic[T]):
    value: T
    source: SourceSpan
    edits: tuple[Edit, ...]
    status: Literal["exact", "normalized", "ambiguous", "invalid"]
    reasons: tuple[str, ...]

判定ステータス (Candidate.status)

  • exact: 原文のまま有効な値(カンマなし数字など)
  • normalized: 非曖昧な正規化(全角半角変換、カンマ除去等)を経て有効な値
  • ambiguous: 複数解釈が可能(2桁西暦、ピリオドによる桁区切りの疑い等)
  • invalid: チェックデジット不一致、存在しない実在日など形式的に不正

フィールド抽出機能一覧

関数名 抽出対象 主な対応内容・検証
find_amounts 金額 円表記(¥, ¥, 円)、3桁区切り、値引き・負数(▲, △, -, 会計括弧 (1,000))、ピリオド混入の曖昧性検出
find_dates 日付 西暦(4桁・2桁)、和暦(令和、平成、昭和、元年、略記 R8.11.15)、実在日検証(うるう年、存在しない日の除外)
find_times 時刻 24時間表記(17:30, 17:30:15)、日本語表記(17時30分)、コロンOCR揺れ(;, .)
find_phone_numbers 電話番号 日本の固定電話、携帯電話(070/080/090)、IP電話(050)、フリーダイヤル(0120/0800)、ハイフン・空白除去
find_invoice_registration_numbers 適格請求書登録番号 T + 13桁、国税庁法人番号チェックデジット(モジュラス9 交互ウェイト)検証
find_jan_codes JAN/EANコード JAN-8 / JAN-13、GS1規格モジュラス10 ウェイト3チェックデジット検証

プロファイル

normalize_text には以下のプロファイルを指定できます:

  • generic: 基本的な全角半角統一、不可視文字・空白の正規化。
  • receipt: レシート頻出の通貨記号、簡体字・異体字辞書(圆・圓 -> 円、计 -> 計、总 -> 総 など)を適用。
  • invoice: 請求書特有のインボイス用語・異体字辞書を適用。

開発とテスト

テストと型検査は以下のコマンドで実行できます。

# テストの実行
pytest

# カバレッジレポート
pytest --cov=jpdoc_normalize --cov-report=term-missing

# 型検査
mypy src

設計思想と非目標

本ライブラリは以下を「非目標」としています:

  • 非目標: OCR推論そのもの、画像傾き補正、レイアウト解析
  • 非目標: LLMによる「おそらくこういう意味だろう」という文脈補完
  • 非目標: 帳票全体を1回でJSON化するエンドツーエンド製品
  • 非目標: 「どの日付・どの金額を採用するか」という業務意思決定

詳細は 設計思想ドキュメント (docs/design_principles.md) をご覧ください。


ライセンス

MIT License

Metadata

Release files for jp-receipt-normalize 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jp-receipt-normalize 0.1.4
File Size Uploaded Provenance Actions
jp_receipt_normalize-0.1.4.tar.gz 37.5 kB With provenance Details for jp_receipt_normalize-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jp-receipt-normalize 0.1.4
File Interpreter ABI Platform Actions
jp_receipt_normalize-0.1.4-py3-none-any.whl Python 3 none any Details for jp_receipt_normalize-0.1.4-py3-none-any.whl

Total release size: 63.6 kB

Release files / jp_receipt_normalize-0.1.4.tar.gz

Download URL jp_receipt_normalize-0.1.4.tar.gz
Size 37.5 kB
Tags Source
SHA-256 checksum
How to use checksums
230520174b0ef14dffcd16880dda1553041cc04f0e3844918e6a3a8a0a1a2d57
BLAKE2b-256 checksum
How to use checksums
36bf6146da3ef36826a292f01b8106a78bf394fe9479366baff5ee1bad7caf77
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / jp_receipt_normalize-0.1.4-py3-none-any.whl

Download URL jp_receipt_normalize-0.1.4-py3-none-any.whl
Size 26.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
44adbf1784ad2521d1bb37d025ade87afb076596f7327ee8995061ce06f4b740
BLAKE2b-256 checksum
How to use checksums
9d4a39a3ac42f3393a61c2498dd8d9a2aa73c0f73eb672629979b4cfa14a7a7d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for jp-receipt-normalize 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for jp_receipt_normalize-0.1.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page