jp-receipt-normalize
日本語帳票OCRの監査可能な正規化・候補抽出ライブラリ
English README is available here (README_en.md) | 設計思想: なぜ曖昧なら直さないか (docs/design_principles.md)
概要
日本語の領収書・レシート・請求書をOCR処理すると、全角半角、Unicode字形、簡体字・異体字、記号の誤読、空白、桁区切りなどが揺れる場合があります。
しかし、業務自動化において「それらしく見える値へ勝手に直す」ことは、誤請求や税務申告ミスを引き起こす危険があります。
jp-receipt-normalize は、OCRエンジンやLLMを内包しない、OCR後段の処理を対象とした監査可能な部品です。
元の文字列、変更箇所、適用規則、曖昧性の理由を記録・保持したうえで、候補を抽出します。
特徴
- 監査可能性:
文字列の変更は
Edit(rule, source, replacement, start, end)として記録され、元の位置と差分を追跡できます。 - 曖昧な補正を自動確定しない:
「O」と「0」、「l」と「1」、ピリオド桁区切り(
¥1.840)など、文脈なしに断定できない曖昧な補正は自動確定せず、status="ambiguous"や判定理由(reasons)を返します。 - 日本語帳票向けの候補抽出:
- 金額(負数・値引き・税額・通貨記号・桁区切り)
- 日付(西暦・和暦・令和元年・実在日うるう年検証)
- 時刻(24時間表記・時分秒・コロン揺れ)
- 日本の電話番号(市外局番体系・固定・携帯・フリーダイヤル・IP電話・ハイフン除去)
- 適格請求書発行事業者登録番号(
T+ 13桁・国税庁法人番号チェックデジット検証) - JAN/EANコード(8桁・13桁・モジュラス10ウェイト3チェックデジット検証)
- 外部通信なし・ゼロ依存: Python標準ライブラリ中心で動作します。外部API呼び出しやネットワーク通信は行わず、決定論的に動作します。
- 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) をご覧ください。
ライセンス
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.