jp-receipt-normalize 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,225 @@
1
+ Metadata-Version: 2.5
2
+ Name: jp-receipt-normalize
3
+ Version: 0.1.0
4
+ Summary: Auditable normalization and candidate extraction for Japanese document OCR
5
+ Project-URL: Homepage, https://github.com/IT-Engineer-K/jp-receipt-normalize
6
+ Project-URL: Repository, https://github.com/IT-Engineer-K/jp-receipt-normalize
7
+ Project-URL: Changelog, https://github.com/IT-Engineer-K/jp-receipt-normalize/blob/main/CHANGELOG.md
8
+ Author: jp-receipt-normalize contributors
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Text Processing :: General
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.10
23
+ Provides-Extra: dev
24
+ Requires-Dist: mypy>=1.0.0; extra == 'dev'
25
+ Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
26
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
27
+ Requires-Dist: ruff>=0.1.0; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # jp-receipt-normalize
31
+
32
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
33
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
34
+ [![Typing: Typed](https://img.shields.io/badge/typing-typed-green.svg)](https://peps.python.org/pep-0561/)
35
+
36
+ **日本語帳票OCRの監査可能な正規化・候補抽出ライブラリ**
37
+
38
+ [English README is available here (README_en.md)](README_en.md) | [設計思想: なぜ曖昧なら直さないか (docs/design_principles.md)](docs/design_principles.md)
39
+
40
+ ---
41
+
42
+ ## 概要
43
+
44
+ 日本語の領収書・レシート・請求書をOCR処理すると、全角半角、Unicode字形、中国語字形(簡体字)、記号の誤読、空白、桁区切りなどが揺れます。
45
+
46
+ しかし、業務自動化において「それらしく見える値へ勝手に直す(サイレント確定)」ことは、誤請求や税務申告ミスを引き起こす極めて危険な行為です。
47
+
48
+ `jp-receipt-normalize` は、**OCRエンジンやLLMを一切内包せず**、OCR後段の処理に特化した監査可能(Auditable)な部品です。
49
+ 元の文字列、変更箇所、適用規則、曖昧性の理由をすべて記録・保持し、安全な候補抽出を提供します。
50
+
51
+ ### 特徴
52
+
53
+ 1. **完全な監査可能性(Auditability)**:
54
+ すべての文字列変更は `Edit(rule, source, replacement, start, end)` として記録され、元の位置と差分を100%追跡できます。
55
+ 2. **サイレント確定の排除**:
56
+ 「O」と「0」、「l」と「1」、ピリオド桁区切り(`¥1.840`)など、文脈なしに断定できない曖昧な補正は自動確定せず、`status="ambiguous"` や判定理由(`reasons`)を返します。
57
+ 3. **日本語帳票に特化した候補抽出**:
58
+ - 金額(負数・値引き・税額・通貨記号・桁区切り)
59
+ - 日付(西暦・和暦・令和元年・実在日うるう年検証)
60
+ - 時刻(24時間表記・時分秒・コロン揺れ)
61
+ - 日本の電話番号(市外局番体系・固定・携帯・フリーダイヤル・IP電話・ハイフン除去)
62
+ - 適格請求書発行事業者登録番号(`T` + 13桁・国税庁法人番号チェックデジット検証)
63
+ - JAN/EANコード(8桁・13桁・モジュラス10ウェイト3チェックデジット検証)
64
+ 4. **外部通信なし・ゼロ依存**:
65
+ Python標準ライブラリ中心で動作。外部API呼び出しやネットワーク通信は一切行わず、決定論的(Deterministic)に動作します。
66
+ 5. **JSON直列化可能 & 厳格な型付け**:
67
+ `to_dict()` による完全なJSON対応と、`py.typed` による静的型チェック(mypy strict)に対応。
68
+
69
+ ---
70
+
71
+ ## インストール
72
+
73
+ ```bash
74
+ pip install jp-receipt-normalize
75
+ ```
76
+
77
+ ---
78
+
79
+ ## クイックスタート
80
+
81
+ ```python
82
+ from jpdoc_normalize import normalize_text
83
+ from jpdoc_normalize.fields import (
84
+ find_amounts,
85
+ find_dates,
86
+ find_invoice_registration_numbers,
87
+ find_phone_numbers,
88
+ )
89
+
90
+ # 1. 文字列の監査可能正規化
91
+ ocr_text = "合 計 ¥1,840"
92
+ normalized = normalize_text(ocr_text, profile="receipt")
93
+
94
+ print(normalized.text)
95
+ # => "合 計 ¥1,840"
96
+
97
+ # 変更履歴(Edit)の確認
98
+ for edit in normalized.edits:
99
+ print(f"Rule: {edit.rule}, Source: {edit.source!r} -> {edit.replacement!r} [{edit.start}:{edit.end}]")
100
+ # => Rule: normalize_space, Source: ' ' -> ' ' [2:3]
101
+ # => Rule: fullwidth_digit_to_halfwidth, Source: '8' -> '8' [5:6]
102
+ # => Rule: fullwidth_digit_to_halfwidth, Source: '4' -> '4' [6:7]
103
+ # => Rule: fullwidth_digit_to_halfwidth, Source: '0' -> '0' [7:8]
104
+
105
+ # 2. 金額候補の抽出
106
+ amounts = find_amounts(normalized)
107
+ print(amounts[0].value, amounts[0].status, amounts[0].reasons)
108
+ # => 1840 normalized ('has_currency_symbol',)
109
+
110
+ # 3. インボイス登録番号の抽出と法人番号チェックデジット検証
111
+ registrations = find_invoice_registration_numbers("登録番号 T6120001018791")
112
+ for candidate in registrations:
113
+ print(candidate.value, candidate.status, candidate.reasons)
114
+ # => T6120001018791 normalized ('has_registration_keyword', 'valid_corporate_number_checksum')
115
+ ```
116
+
117
+ ---
118
+
119
+ ## 主要データ型
120
+
121
+ ### `SourceSpan`
122
+ 元のOCR入力におけるテキストスパン、座標情報、信頼度を保持します。
123
+
124
+ ```python
125
+ @dataclass(frozen=True)
126
+ class SourceSpan:
127
+ text: str
128
+ start: int
129
+ end: int
130
+ page: int | None = None
131
+ bbox: tuple[float, float, float, float] | None = None
132
+ confidence: float | None = None
133
+ engine: str | None = None
134
+ ```
135
+
136
+ ### `Edit`
137
+ テキスト正規化における1つの編集操作。監査証跡として保存されます。
138
+
139
+ ```python
140
+ @dataclass(frozen=True)
141
+ class Edit:
142
+ rule: str
143
+ source: str
144
+ replacement: str
145
+ start: int
146
+ end: int
147
+ ```
148
+
149
+ ### `Candidate[T]`
150
+ 抽出されたフィールドの候補値。判定ステータスと根拠理由を持ちます。
151
+
152
+ ```python
153
+ @dataclass(frozen=True)
154
+ class Candidate(Generic[T]):
155
+ value: T
156
+ source: SourceSpan
157
+ edits: tuple[Edit, ...]
158
+ status: Literal["exact", "normalized", "ambiguous", "invalid"]
159
+ reasons: tuple[str, ...]
160
+ ```
161
+
162
+ #### 判定ステータス (`Candidate.status`)
163
+ - `exact`: 原文のまま有効な値(カンマなし数字など)
164
+ - `normalized`: 非曖昧な正規化(全角半角変換、カンマ除去等)を経て有効な値
165
+ - `ambiguous`: 複数解釈が可能(2桁西暦、ピリオドによる桁区切りの疑い等)
166
+ - `invalid`: チェックデジット不一致、存在しない実在日など形式的に不正
167
+
168
+ ---
169
+
170
+ ## フィールド抽出機能一覧
171
+
172
+ | 関数名 | 抽出対象 | 主な対応内容・検証 |
173
+ |---|---|---|
174
+ | `find_amounts` | 金額 | 円表記(`¥`, `¥`, `円`)、3桁区切り、値引き・負数(`▲`, `△`, `-`, 会計括弧 `(1,000)`)、ピリオド混入の曖昧性検出 |
175
+ | `find_dates` | 日付 | 西暦(4桁・2桁)、和暦(令和、平成、昭和、元年、略記 `R8.11.15`)、実在日検証(うるう年、存在しない日の除外) |
176
+ | `find_times` | 時刻 | 24時間表記(`17:30`, `17:30:15`)、日本語表記(`17時30分`)、コロンOCR揺れ(`;`, `.`) |
177
+ | `find_phone_numbers` | 電話番号 | 日本の固定電話、携帯電話(070/080/090)、IP電話(050)、フリーダイヤル(0120/0800)、ハイフン・空白除去 |
178
+ | `find_invoice_registration_numbers` | 適格請求書登録番号 | `T` + 13桁、国税庁法人番号チェックデジット(モジュラス9 交互ウェイト)検証 |
179
+ | `find_jan_codes` | JAN/EANコード | JAN-8 / JAN-13、GS1規格モジュラス10 ウェイト3チェックデジット検証 |
180
+
181
+ ---
182
+
183
+ ## プロファイル
184
+
185
+ `normalize_text` には以下のプロファイルを指定できます:
186
+
187
+ - `generic`: 基本的な全角半角統一、不可視文字・空白の正規化。
188
+ - `receipt`: レシート頻出の通貨記号、簡体字・異体字辞書(`圆`・`圓`・`元` -> `円`、`计` -> `計`、`总` -> `総` など)を適用。
189
+ - `invoice`: 請求書特有のインボイス用語・異体字辞書を適用。
190
+
191
+ ---
192
+
193
+ ## 開発とテスト
194
+
195
+ 本ライブラリは、高いテストカバレッジと型安全性を重視しています。
196
+
197
+ ```bash
198
+ # テストの実行
199
+ pytest
200
+
201
+ # カバレッジレポート
202
+ pytest --cov=jpdoc_normalize --cov-report=term-missing
203
+
204
+ # 型検査
205
+ mypy src
206
+ ```
207
+
208
+ ---
209
+
210
+ ## 設計思想と非目標
211
+
212
+ 本ライブラリは以下の「非目標」を明確に定めています:
213
+
214
+ - **非目標**: OCR推論そのもの、画像傾き補正、レイアウト解析
215
+ - **非目標**: LLMによる「おそらくこういう意味だろう」という文脈補完
216
+ - **非目標**: 帳票全体を1回でJSON化するエンドツーエンド製品
217
+ - **非目標**: 「どの日付・どの金額を採用するか」という業務意思決定
218
+
219
+ 詳細は [設計思想ドキュメント (docs/design_principles.md)](docs/design_principles.md) をご覧ください。
220
+
221
+ ---
222
+
223
+ ## ライセンス
224
+
225
+ [MIT License](LICENSE)
@@ -0,0 +1,17 @@
1
+ jpdoc_normalize/__init__.py,sha256=7awQyT50FQRCvCWsJaQDY3r93Hhkkt_L6MzSxRDt22c,680
2
+ jpdoc_normalize/char_maps.py,sha256=Gxm69Sqf8uYjrZ_jlaOQ_huPfhKDZys4T-YszECNvRY,3258
3
+ jpdoc_normalize/models.py,sha256=_xQFDCLBk_U74AryoZpSbBfOe_PGdRCGtI18t4xUkfg,2949
4
+ jpdoc_normalize/normalizer.py,sha256=-eZkGlroGa3A32UVRitOOR46AsvWYww5HvnmJsQDyN8,7556
5
+ jpdoc_normalize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ jpdoc_normalize/utils.py,sha256=9Mxl2ToPa0ColuvWmn_RjlPx__PcopUAXyk00Cuk4NI,3139
7
+ jpdoc_normalize/fields/__init__.py,sha256=RquAqoonassd-7-TXla9C2VLyBPJ9lUXCDR_DkL2fR4,549
8
+ jpdoc_normalize/fields/amount.py,sha256=fP-qZZH8Rey7uR1S6zIAaOp8oDqd3pu55s0PZpPpDPE,6724
9
+ jpdoc_normalize/fields/date.py,sha256=M6U5QcsnUW5qhHvpNk8Bu-m4GOJnxRAKkMCIjNLuDwI,6421
10
+ jpdoc_normalize/fields/jan.py,sha256=_86FXOGS6Rj_3Rz-TmDMkyuCCDPuzoALLCxJL41jWJs,3362
11
+ jpdoc_normalize/fields/phone.py,sha256=eq-GYEY8XrqsxgD6Xjhqv7mX-W2ZnCsQUOkNnNUfDQc,4056
12
+ jpdoc_normalize/fields/registration.py,sha256=hrhCw05N7NLJHmHfCuBSzuFUtVezLyuu15h6SmGaGEk,4248
13
+ jpdoc_normalize/fields/time.py,sha256=9T-rBsH-Vq9exq14tYtveRCrbBMhcjaO3Cs9jxsqOo4,4421
14
+ jp_receipt_normalize-0.1.0.dist-info/METADATA,sha256=LCy8DXR_5waOKwLfkPg1ALzOLFuLhjNjBQsk9DPW4nk,9440
15
+ jp_receipt_normalize-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
16
+ jp_receipt_normalize-0.1.0.dist-info/licenses/LICENSE,sha256=V6twn2pY7pxPanC2f_9dGsq73OWtuFQH23LOnxNvt6I,1090
17
+ jp_receipt_normalize-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 jp-receipt-normalize contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,35 @@
1
+ from __future__ import annotations
2
+
3
+ from jpdoc_normalize.fields import (
4
+ find_amounts,
5
+ find_dates,
6
+ find_jan_codes,
7
+ find_phone_numbers,
8
+ find_invoice_registration_numbers,
9
+ find_times,
10
+ )
11
+ from jpdoc_normalize.models import (
12
+ Candidate,
13
+ CandidateStatus,
14
+ Edit,
15
+ NormalizedText,
16
+ SourceSpan,
17
+ )
18
+ from jpdoc_normalize.normalizer import normalize_text
19
+
20
+ __version__ = "0.1.0"
21
+
22
+ __all__ = [
23
+ "normalize_text",
24
+ "SourceSpan",
25
+ "Edit",
26
+ "Candidate",
27
+ "CandidateStatus",
28
+ "NormalizedText",
29
+ "find_amounts",
30
+ "find_dates",
31
+ "find_times",
32
+ "find_phone_numbers",
33
+ "find_invoice_registration_numbers",
34
+ "find_jan_codes",
35
+ ]
@@ -0,0 +1,92 @@
1
+ from __future__ import annotations
2
+
3
+ # Invisible / Zero-width characters to remove
4
+ ZERO_WIDTH_CHARS = {
5
+ "\u200B": "zero_width_space",
6
+ "\uFEFF": "zero_width_no_break_space",
7
+ "\u200C": "zero_width_non_joiner",
8
+ "\u200D": "zero_width_joiner",
9
+ "\u200E": "left_to_right_mark",
10
+ "\u200F": "right_to_left_mark",
11
+ "\u202A": "left_to_right_embedding",
12
+ "\u202B": "right_to_left_embedding",
13
+ "\u202C": "pop_directional_formatting",
14
+ "\u202D": "left_to_right_override",
15
+ "\u202E": "right_to_left_override",
16
+ }
17
+
18
+ # Whitespace normalization mapping (to standard half-width space ' ')
19
+ SPACE_CHARS = {
20
+ "\u3000": "ideographic_space",
21
+ "\u00A0": "no_break_space",
22
+ "\u2002": "en_space",
23
+ "\u2003": "em_space",
24
+ "\u2004": "three_per_em_space",
25
+ "\u2005": "four_per_em_space",
26
+ "\u2006": "six_per_em_space",
27
+ "\u2007": "figure_space",
28
+ "\u2008": "punctuation_space",
29
+ "\u2009": "thin_space",
30
+ "\u202F": "narrow_no_break_space",
31
+ "\u205F": "medium_mathematical_space",
32
+ }
33
+
34
+ # Hyphen / Dash variants
35
+ HYPHEN_CHARS = {
36
+ "\u2010": "hyphen",
37
+ "\u2011": "non_breaking_hyphen",
38
+ "\u2012": "figure_dash",
39
+ "\u2013": "en_dash",
40
+ "\u2014": "em_dash",
41
+ "\u2015": "horizontal_bar",
42
+ "\u2212": "minus_sign",
43
+ "\uFF0D": "fullwidth_hyphen_minus",
44
+ "\uFE63": "small_hyphen_minus",
45
+ "\u2500": "box_drawings_light_horizontal",
46
+ "\uFF70": "halfwidth_katakana_hiragana_prolonged_sound_mark",
47
+ }
48
+
49
+ # Currency symbols
50
+ CURRENCY_MAP = {
51
+ "\uFFE5": ("¥", "fullwidth_yen"),
52
+ "\u005C": ("¥", "backslash_as_yen"), # In Japanese fonts \ is often rendered as ¥
53
+ }
54
+
55
+ # Fullwidth ASCII to halfwidth mapping (range 0xFF01 - 0xFF5E)
56
+ # Maps !"#$%&'()*+,-./0-9:;<=>?@A-Z[\]^_`a-z{|}~
57
+ FULLWIDTH_TO_HALFWIDTH: dict[str, str] = {}
58
+ for code in range(0xFF01, 0xFF5F):
59
+ FULLWIDTH_TO_HALFWIDTH[chr(code)] = chr(code - 0xFEE0)
60
+
61
+ # Simplified Chinese / Han variant characters common in Japanese OCR
62
+ # Map from variant to standard Japanese JOD (Joyo / Jinmeiyo kanji)
63
+ SIMPLIFIED_TO_JAPANESE_COMMON: dict[str, tuple[str, str]] = {
64
+ "圆": ("円", "simplified_yuan_to_yen"),
65
+ "圓": ("円", "traditional_yuan_to_yen"),
66
+ "计": ("計", "simplified_ji_to_kei"),
67
+ "总": ("総", "simplified_zong_to_so"),
68
+ "额": ("額", "simplified_e_to_gaku"),
69
+ "领": ("領", "simplified_ling_to_ryo"),
70
+ "收": ("収", "simplified_shou_to_shu"),
71
+ "证": ("証", "simplified_zheng_to_sho"),
72
+ "购": ("購", "simplified_gou_to_ko"),
73
+ "录": ("録", "simplified_lu_to_roku"),
74
+ "开": ("開", "simplified_kai_to_kai"),
75
+ "发": ("発", "simplified_fa_to_hatsu"),
76
+ "卖": ("売", "simplified_mai_to_uri"),
77
+ "费": ("費", "simplified_fei_to_hi"),
78
+ "银": ("銀", "simplified_yin_to_gin"),
79
+ "联": ("聯", "simplified_lian_to_ren"),
80
+ "码": ("碼", "simplified_ma_to_ma"),
81
+ }
82
+
83
+ # Receipt-specific variant mappings
84
+ RECEIPT_VARIANTS: dict[str, tuple[str, str]] = {
85
+ **SIMPLIFIED_TO_JAPANESE_COMMON,
86
+ "元": ("円", "currency_yuan_to_yen"), # Only in currency contexts or receipt profile
87
+ }
88
+
89
+ # Invoice-specific variant mappings
90
+ INVOICE_VARIANTS: dict[str, tuple[str, str]] = {
91
+ **SIMPLIFIED_TO_JAPANESE_COMMON,
92
+ }
@@ -0,0 +1,17 @@
1
+ from __future__ import annotations
2
+
3
+ from jpdoc_normalize.fields.amount import find_amounts
4
+ from jpdoc_normalize.fields.date import find_dates
5
+ from jpdoc_normalize.fields.jan import find_jan_codes
6
+ from jpdoc_normalize.fields.phone import find_phone_numbers
7
+ from jpdoc_normalize.fields.registration import find_invoice_registration_numbers
8
+ from jpdoc_normalize.fields.time import find_times
9
+
10
+ __all__ = [
11
+ "find_amounts",
12
+ "find_dates",
13
+ "find_times",
14
+ "find_phone_numbers",
15
+ "find_invoice_registration_numbers",
16
+ "find_jan_codes",
17
+ ]
@@ -0,0 +1,184 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ from typing import Any
5
+
6
+ from jpdoc_normalize.models import Candidate, CandidateStatus, Edit, NormalizedText, SourceSpan
7
+ from jpdoc_normalize.utils import ensure_normalized, map_span_to_source
8
+
9
+ # Regex patterns for amounts
10
+ # Matches currency symbols, negative signs, digits with commas or periods, and optional "円"
11
+ AMOUNT_PATTERN = re.compile(
12
+ r"""
13
+ (?P<prefix>
14
+ [▲△▼▽\-−–—-]|\( |
15
+ [¥¥\\$€] |
16
+ (?:値引|割引|内税|外税|消費税|税込|税抜|小計|合計|合\s*計|お預り|お釣り?|御買上|対象計|請求額)\s*[::]?\s*
17
+ )?
18
+ \s*
19
+ (?P<currency_sym>[¥¥\\$€])?
20
+ \s*
21
+ (?P<sign>[▲△\-−–—-]|\()?\s*
22
+ (?P<number>
23
+ \d{1,3}(?:,\d{3})+ | # standard comma separated: 1,840 / 10,000,000
24
+ \d{1,3}(?:\.\d{3})+ | # period as thousand separator: 1.840
25
+ \d+(?:\.\d{1,2})? # plain digits with optional decimal: 1840 / 1840.50
26
+ )
27
+ \s*(?P<closing_paren>\))?
28
+ \s*(?P<suffix_hyphen>[-−–—-])?
29
+ \s*(?P<suffix>円)?
30
+ """,
31
+ re.VERBOSE,
32
+ )
33
+
34
+
35
+ def find_amounts(
36
+ text_or_normalized: str | SourceSpan | NormalizedText,
37
+ *,
38
+ require_currency_or_context: bool = False,
39
+ ) -> list[Candidate[int]]:
40
+ """
41
+ Extract money amount candidates from Japanese document text.
42
+
43
+ Args:
44
+ text_or_normalized: Input text, SourceSpan, or NormalizedText.
45
+ require_currency_or_context: If True, only extract amounts accompanied by
46
+ a currency symbol (¥, ¥, 円) or financial keyword.
47
+
48
+ Returns:
49
+ List of Candidate[int] objects.
50
+ """
51
+ normalized = ensure_normalized(text_or_normalized, profile="receipt")
52
+ text = normalized.text
53
+ candidates: list[Candidate[int]] = []
54
+
55
+ for match in AMOUNT_PATTERN.finditer(text):
56
+ number_str = match.group("number")
57
+ if not number_str:
58
+ continue
59
+
60
+ prefix = match.group("prefix") or ""
61
+ currency_sym = match.group("currency_sym") or ""
62
+ sign_char = match.group("sign") or ""
63
+ closing_paren = match.group("closing_paren") or ""
64
+ suffix = match.group("suffix") or ""
65
+ suffix_hyphen = match.group("suffix_hyphen") or ""
66
+
67
+ has_currency_hint = bool(
68
+ currency_sym
69
+ or suffix == "円"
70
+ or any(s in prefix for s in ["¥", "¥", "\\", "$", "€"])
71
+ )
72
+ has_context_hint = bool(
73
+ any(
74
+ kw in prefix
75
+ for kw in [
76
+ "値引",
77
+ "割引",
78
+ "税",
79
+ "小計",
80
+ "合計",
81
+ "お預",
82
+ "お釣",
83
+ "買上",
84
+ "請求",
85
+ ]
86
+ )
87
+ )
88
+
89
+ if require_currency_or_context and not (has_currency_hint or has_context_hint):
90
+ continue
91
+
92
+ # If it's just a bare 1-2 digit number without any hint, skip to avoid noise (e.g. page numbers)
93
+ if not (has_currency_hint or has_context_hint) and len(number_str) < 3 and "," not in number_str:
94
+ continue
95
+
96
+ # Determine actual token span (excluding preceding keyword context)
97
+ # Find start position of currency symbol, sign, or number
98
+ token_start = match.start("number")
99
+ if currency_sym and match.start("currency_sym") < token_start:
100
+ token_start = match.start("currency_sym")
101
+ if sign_char and match.start("sign") < token_start:
102
+ token_start = match.start("sign")
103
+ elif prefix.endswith("(") and closing_paren:
104
+ token_start = match.start("prefix") + len(prefix) - 1
105
+
106
+ token_end = match.end("number")
107
+ if closing_paren and match.end("closing_paren") > token_end:
108
+ token_end = match.end("closing_paren")
109
+ if suffix_hyphen and match.end("suffix_hyphen") > token_end:
110
+ token_end = match.end("suffix_hyphen")
111
+ if suffix and match.end("suffix") > token_end:
112
+ token_end = match.end("suffix")
113
+
114
+ # Accounting parentheses: e.g. (1,000) or (¥1,000)
115
+ has_opening_paren = (sign_char == "(") or (prefix.endswith("(") and token_start < match.start("number"))
116
+ has_closing_paren = bool(closing_paren)
117
+ is_accounting_parens = has_opening_paren and has_closing_paren
118
+
119
+ # Negative determination
120
+ is_negative = False
121
+ if any(kw in prefix for kw in ["▲", "△", "▼", "▽", "値引", "割引"]):
122
+ is_negative = True
123
+ elif sign_char in ["▲", "△", "-", "−", "–", "—", "-"]:
124
+ is_negative = True
125
+ elif is_accounting_parens:
126
+ is_negative = True
127
+
128
+ reasons: list[str] = []
129
+ status: CandidateStatus = "normalized"
130
+
131
+ # Check period vs comma ambiguity
132
+ # E.g. "1.840" -> 3 digits after period could be OCR error for "1,840"
133
+ period_as_comma = False
134
+ if "." in number_str:
135
+ parts = number_str.split(".")
136
+ if len(parts) == 2 and len(parts[1]) == 3 and not parts[0].endswith(","):
137
+ # Could be 1.840 (thousands separator OCR misread as period)
138
+ period_as_comma = True
139
+ status = "ambiguous"
140
+ reasons.append("period_used_as_thousands_separator_candidate")
141
+
142
+ # Parse numeric value
143
+ clean_num = number_str.replace(",", "")
144
+ if period_as_comma:
145
+ clean_num = clean_num.replace(".", "")
146
+
147
+ try:
148
+ val_float = float(clean_num)
149
+ val_int = int(round(val_float))
150
+ if is_negative:
151
+ val_int = -abs(val_int)
152
+ except ValueError:
153
+ status = "invalid"
154
+ reasons.append("numeric_parse_failed")
155
+ val_int = 0
156
+
157
+ # Determine exact vs normalized
158
+ matched_slice = text[token_start:token_end]
159
+ source_span, edits = map_span_to_source(token_start, token_end, normalized)
160
+
161
+ if status != "ambiguous" and status != "invalid":
162
+ if not edits and matched_slice == str(val_int):
163
+ status = "exact"
164
+ else:
165
+ status = "normalized"
166
+
167
+ if has_currency_hint:
168
+ reasons.append("has_currency_symbol")
169
+ if has_context_hint:
170
+ reasons.append("has_context_keyword")
171
+ if is_negative:
172
+ reasons.append("negative_amount")
173
+
174
+ candidates.append(
175
+ Candidate(
176
+ value=val_int,
177
+ source=source_span,
178
+ edits=edits,
179
+ status=status,
180
+ reasons=tuple(reasons),
181
+ )
182
+ )
183
+
184
+ return candidates