pdf-statement-parser

PDF 明細書パーサー

目次

• 概要
• 入力仕様
• ワークフロー
• 書類タイプ別プレイブック
• 出力仕様
• 信頼度スコアリング
• ガードレール
• 例

概要

銀行、証券、退職年金、HSA、住宅ローンの明細書は、さまざまな独自の書式で PDF として届きます。このスキルは、プロンプト駆動型の抽出手法です。書類タイプを特定し、位置ではなくラベルを手がかりに標準項目を見つけ、すべての取引行または保有銘柄行を取得して、厳密な JSON レコードを出力します。すべての金額は整数のセントに、すべての日付は**ISO 8601（YYYY-MM-DD）**に変換します。

Claude の PDF 読み取り機能で直接使用できます。PDF をReadし、表示された内容に対してこのスキルのワークフローを実行します。外部ライブラリは不要です。

入力仕様

呼び出し元は次の情報を提供します。

• pdf_path — 単一の明細書 PDF の絶対パス。
• expected_type（任意）— checking_statement | savings_statement | credit_card_statement | brokerage_statement | 401k_statement | hsa_statement | mortgage_statement | tax_form | insurance_doc | unknown のいずれか。指定がない場合、スキルが判定します。
• known_accounts（任意）— 照合用の {id, institution, mask, type} 配列。

ワークフロー

- [ ] Step 1: Read the PDF (first pass: pages 1-2 for header)
- [ ] Step 2: Detect document type from header keywords
- [ ] Step 3: Extract account identity (institution + mask + type)
- [ ] Step 4: Extract statement period (start/end dates)
- [ ] Step 5: Extract balance markers (opening / closing / available)
- [ ] Step 6: Extract line items (transactions, holdings, or events)
- [ ] Step 7: Normalize to integer cents and ISO dates
- [ ] Step 8: Score confidence on each field; emit JSON

ステップ 1 — PDF を読み込む

PDF のパスを指定してReadツールを使用します。10 ページを超える PDF は、ページ 1～5（ヘッダーと最初の取引）を読み込み、その後、必要に応じて続きの範囲を読み込みます。総ページ数を記録します。

ステップ 2 — 書類タイプを判定する

次のヘッダー上の手がかりを確認します（優先度の高い順）。

手がかり	書類タイプ
「Statement of Account」＋「Available Balance」＋当座預金形式の取引	checking_statement
「Savings Statement」／「Money Market Statement」	savings_statement
「Credit Card Statement」＋「Payment Due」＋「Minimum Payment」	credit_card_statement
「Account Summary」＋「Holdings」＋ティッカーシンボル	brokerage_statement
「401(k) Statement」／「Retirement Plan」＋「Vested Balance」	401k_statement
「Health Savings Account」／「HSA」＋「Contribution Limit」	hsa_statement
「Mortgage Statement」＋「Principal」＋「Escrow」	mortgage_statement
「W-2」／「1099」／「1098」／「5498」のフォーム番号	tax_form
保険証券の明細ページ、保険料、免責額	insurance_doc

2 つの手がかりが同程度の場合は、書類タイトルまたはページヘッダーに記載されている方を優先します。

ステップ 3 — 口座情報を抽出する

• 金融機関：ページ上部のロゴのテキスト、または「Issued by」／「Statement from」ラベル。
• マスク：末尾 4 桁。「****1234」、「xxxx1234」、「Account ending in 1234」、または金融機関が使用するマスキング形式を検索します。常に ****1234 の形式で保存します。
• 口座タイプ：上記§2と表示ラベル（「Checking」、「Visa Signature」、「Roth IRA」など）から判定します。
• 口座名義人：口座保有者の氏名（後続処理でhousehold.jsonのメンバーとの照合に使用）。

(institution, mask) を使ってknown_accountsと照合します。一致する口座がない場合は、account_match: "new"とし、acc_<type>_<incrementing>のようなaccount_idを提案します。

ステップ 4 — 明細書の期間を抽出する

「Statement Period」、「Cycle Date」、「Closing Date」、「Period Beginning … Period Ending」というラベルを探します。次を出力します。

• period_start — 対象期間の初日（ISO）。
• period_end — 対象期間の最終日。明細書の締め日でもあります（ISO）。

締め日だけが記載されている場合は、period_end = closing_date、period_start = nullとし、期間のconfidence: 0.6を設定します。

ステップ 5 — 残高マーカーを抽出する

現金／クレジット口座の場合：opening_balance_cents、closing_balance_cents、available_balance_cents（記載されている場合）。クレジットカードの場合は、さらに statement_balance_cents、minimum_payment_cents、payment_due_date も抽出します。

証券口座／401k／HSA の場合：total_value_cents、cash_cents、invested_cents。期首／期末の取引残高は対象外です。これらは保有資産明細です。

住宅ローンの場合：current_principal_cents、monthly_pi_cents、monthly_escrow_cents、next_payment_due、extra_principal_ytd_cents。

ステップ 6 — 明細項目を抽出する

3 つのモードがあります。

現金／クレジット取引。 取引テーブルの各行から、date、post_date（別の列にある場合）、description_raw、amount を取得します。符号規則：支出は負、入金は正です。明細書に「Withdrawals」と「Deposits」の 2 列がある場合は、それに応じて符号を設定します。description_raw は印字どおりに正確に保持してください。マーチャント名は後で帳簿担当者が正規化します。

証券口座／401k／HSA の保有資産。 保有資産の各行から、symbol、description、shares（小数）、price（1 株あたり）、value、cost_basis（記載されている場合）、asset_class（ファンドの説明から割り当て。以下のプレイブックを参照）を取得します。

住宅ローンの取引履歴。 最近の支払いテーブルから、各項目の date、total_paid_cents、principal_cents、interest_cents、escrow_cents、extra_principal_cents を取得します。

税務フォーム。 プレイブックに従い、フォーム固有のフィールドを取得します（W-2 のボックス、1099-DIV の通常配当／適格配当、1098 の住宅ローン支払利息、5498-SA の HSA 拠出額）。

ステップ 7 — 正規化する

• 金額：$1,247.50 → 124750 セント。支出は負の値：-$87.42 → -8742。
• 日付：01/15/26 → 2026-01-15。2 桁の年は、文脈から別の年と判断できない限り、現在の世紀として扱います。
• 説明の前後の空白を削除し、大文字・小文字はそのまま保持します。

ステップ 8 — 信頼度をスコア化する

各フィールドに [0.0, 1.0] の範囲で信頼度を割り当てます。

• 1.0 — ラベル付きフィールドから直接抽出した値。
• 0.85–0.95 — 位置関係から抽出した値（列見出しは推定、値は明確）。
• 0.6–0.8 — 周辺のテキストから推定した値、または一部が OCR で読み取られた値。
• < 0.6 — 人による確認が必要な値としてフラグを立てます。

レコード全体の confidence には、必須フィールドのフィールド別信頼度の最小値を設定します。

書類タイプ別プレイブック

checking_statement / savings_statement

必須項目：institution、mask、period_start、period_end、opening_balance_cents、closing_balance_cents、transactions[]。照合式：opening + Σ(transactions.amount) = closing（±$1 以内）。

credit_card_statement

必須項目：institution、mask、period_start、period_end、opening_balance_cents、closing_balance_cents、statement_balance_cents、minimum_payment_cents、payment_due_date、transactions[]。注：カード会員の視点では、クレジットカードの支出は購入（カード残高には正の値）ですが、世帯全体の統合台帳では、購入を負の値（世帯から出ていくお金）、カードへの支払いを正の値（または内部振替）として扱います。使用した符号規則を記録してください。

brokerage_statement

必須項目：institution、mask、account_type、period_end、total_value_cents、holdings[]。任意項目：cash_cents、transactions[]（購入／売却／配当）。資産クラスの割り当て：

ファンドのヒント	asset_class
「S&P 500」、「Total Stock Market」、「Large Cap Blend」、VOO/VTI/SPY	us_equity
「International」、「Developed Markets」、「Emerging Markets」、VXUS/IXUS	intl_equity
「Total Bond」、「Aggregate Bond」、「Treasury」、BND/AGG	us_bond
「Money Market」、「Cash Reserve」、SPAXX	cash
「REIT」、「Real Estate」	reit
「Target Date 20XX」	target_date（年を記録します）

割り当てられない場合は、信頼度を 0.5 として asset_class: null のままにします。

401k_statement

必須項目：institution、owner、period_end、total_balance_cents、ytd_contribution_cents（記載されている場合）、employer_match_ytd_cents（記載されている場合）、holdings[]。権利確定額の列に注意し、記載されている場合は vested_cents を別途記録します。

hsa_statement

必須項目：institution、period_end、cash_cents、invested_cents、total_cents、ytd_contribution_cents、ytd_distribution_cents（表示されている場合）。記載されている場合は、coverage type も記録してください：self_only または family。

mortgage_statement

必須項目：institution、mask、period_end、current_principal_cents、monthly_pi_cents、monthly_escrow_cents、next_payment_due、recent_payments[]。記載されている場合は、金利 APR も記録してください。

tax_form

必須項目：form_type（W-2、1099-DIV、1099-INT、1099-B、1098、5498-SA、1095）、tax_year、issuer、recipient、key_boxes（フォーム固有）。解釈は税務コンプライアンスエージェントに委ねてください。このスキルでは各欄の値を取得するだけです。

出力仕様

単一の JSON オブジェクトを出力します：

{
  "document_type": "checking_statement",
  "source_path": "inbox/2026-01-15-batch/checking-jan.pdf",
  "institution": "Bank Name",
  "account": {
    "mask": "****1234",
    "type": "checking",
    "owners": ["Jane Doe", "John Doe"],
    "match": "acc_chk_001",
    "match_confidence": 0.95
  },
  "period": {
    "start": "2025-12-15",
    "end": "2026-01-14"
  },
  "balances": {
    "opening_cents": 1124300,
    "closing_cents": 1247500,
    "available_cents": 1247500
  },
  "transactions": [
    {
      "date": "2025-12-16",
      "post_date": "2025-12-17",
      "description_raw": "TRADER JOE'S #123 PORTLAND OR",
      "amount_cents": -8742,
      "confidence": 0.97
    }
  ],
  "reconciliation": {
    "expected_closing_cents": 1247500,
    "computed_closing_cents": 1247500,
    "diff_cents": 0,
    "ok": true
  },
  "extracted_at": "2026-01-20T14:00:00Z",
  "overall_confidence": 0.94,
  "warnings": []
}

brokerage／401k／HSA の場合は、transactions を holdings に置き換え、プレイブックに従って残高フィールドを指定してください。

信頼度スコア

以下の場合は全体の信頼度を下げ、warnings[] エントリーを追加してください：

• 照合差額が 1 ドルを超える場合 → warning: "reconcile_failed: diff $X.XX" と overall_confidence: max(0.5, current * 0.7)。
• 必須フィールドが欠落している場合 → warning: "missing_required: <field>" と overall_confidence ≤ 0.5。
• OCR 品質が低いページ（文字が判読不能な場合）→ warning: "low_ocr_quality_page_<n>" を追加し、フィールドごとの信頼度ペナルティを適用します。
• 保有資産の 20% 超で資産クラスが不明な場合 → warning: "unknown_asset_class_high"。

ガードレール

• 値を決して捏造しないでください。 PDF でフィールドが確認できない場合は null に設定し、警告を追加してください。補間してはいけません。
• ここでは加盟店名を正規化しないでください。 これは簿記担当者の作業です。description_raw はバイト単位でそのまま保持してください。
• ここでは取引を分類しないでください。 分類は後続処理（transaction-categorizer）で行います。
• 現金／クレジットの明細書については、ok: true とする前に必ず照合してください。
• 通貨：明細書に別の記載がない限り、USD とみなしてください。USD 以外の場合は通貨コードを記録し、自動換算しないでください。
• 口座マスクのみ。 口座番号全体を抽出または保存してはいけません。

例

2025-12-15 から 2026-01-14 までの期間を対象とし、開始残高が $11,243.00、合計 $4,832.00 の入金が 3 件、合計 $3,600.00 の出金が 27 件、終了残高が $12,475.00 の 4 ページの Chase 当座預金明細書が与えられた場合、パーサーは次のように出力します：

• document_type: "checking_statement"
• institution: "Chase"
• account.mask: "****1234"、account.type: "checking"
• period.start: "2025-12-15"、period.end: "2026-01-14"
• balances.opening_cents: 1124300、balances.closing_cents: 1247500
• transactions: [...] — 30 件のエントリー。それぞれに description_raw、amount_cents（符号付き）、および 0.92 以上のフィールドごとの信頼度が含まれます
• reconciliation.ok: true、diff_cents: 0
• overall_confidence: 0.95、warnings: []