AI Bank Statement Extraction#

PdfImport uses Anthropic Claude or OpenAI GPT to automatically classify an uploaded PDF and extract its transactions. The pipeline has two stages:

1. Classification (process_with_ai) — identifies the document type (e.g., bank_statement, credit_card_statement, investment_statement) and extracts high-level metadata (institution, period, balances).
2. Transaction extraction (extract_transactions) — runs only for bank_statement / credit_card_statement documents; calls the provider's extract_bank_statement method to pull every transaction from the PDF.

The entire flow is driven asynchronously by ProcessPdfJob (medium_priority queue). After extraction, rows are materialized via generate_rows_from_extracted_data and the import status is set to :pending for user review 1.

PdfImport skips the standard CSV import workflow entirely — requires_csv_workflow? returns false 2.

Processing Pipeline#

PdfImport#process_with_ai_later
  └─ ProcessPdfJob#perform
       ├─ PdfImport#process_with_ai ← Stage 1: classify + metadata
       │ └─ Provider.process_pdf
       │ └─ PdfProcessor#process (Anthropic / OpenAI)
       ├─ [if bank_statement or credit_card_statement]
       │ PdfImport#extract_transactions ← Stage 2: pull every transaction
       │ └─ Provider.extract_bank_statement
       │ └─ BankStatementExtractor#extract
       ├─ PdfImport#generate_rows_from_extracted_data
       └─ PdfImport#sync_mappings

Triggering the job — process_with_ai_later acquires a lock, transitions the import to :importing, and enqueues ProcessPdfJob. A guard at the top of perform releases stuck :importing claims older than 30 minutes back to :pending 3.

Provider selection — both stages call Provider::Registry.preferred_llm_provider, which resolves Anthropic or OpenAI based on Setting.llm_provider and valid credentials. Both providers expose process_pdf and extract_bank_statement methods with the same interface 4.

Vector store upload — after classification, the PDF is also uploaded to the family's vector store for retrieval. Failures here are logged as warnings but do not abort the job 5.

Stage 1 – Document Classification (PdfProcessor)#

Both providers implement a PdfProcessor class for the classification stage. The Anthropic version at Provider::Anthropic::PdfProcessor sends the raw PDF as a base64-encoded document content block (native PDF support), while the OpenAI version renders it differently.

The PdfProcessor forces a structured output via a single tool call (report_document_analysis) and returns a PdfProcessingResult with:

The Anthropic processor enforces a 32 MB raw-PDF cap (accounts for base64 overhead in the request body) 6. max_tokens defaults to 4,096 and is overridden via ANTHROPIC_MAX_TOKENS 7.

Classification instructions are strict: the model is told to be factual, return null for unclear fields, and never invent figures 8.

Stage 2 – Transaction Extraction (BankStatementExtractor)#

The two provider implementations take very different approaches:

Anthropic (Provider::Anthropic::BankStatementExtractor)#

• Sends the entire PDF as a single native document block (base64, application/pdf) in one API call 9.
• Forces a single report_bank_statement tool call 10 returning a structured schema with bank_name, account_holder, account_number, statement_period, opening_balance, closing_balance, and a transactions array.
• Each transaction requires date (YYYY-MM-DD), description, and amount (negative = debit) 11.
• No deduplication — since the whole PDF is processed as one unit, duplicate-row merging would incorrectly collapse legitimately identical same-day transactions 12.
• Detects response truncation via stop_reason == :max_tokens and logs a warning 13. Raise ANTHROPIC_MAX_TOKENS env var if statements are being cut short.
• Records token usage + Langfuse spans for every call 14.

OpenAI (Provider::Openai::BankStatementExtractor)#

• Uses PDF::Reader to extract page text, then splits pages into chunks of up to 3,000 characters 15.
• Each chunk is sent as a separate chat completion call with response_format: { type: "json_object" } 16.
• Statement metadata (bank name, period, balances) is captured from the first chunk only 17.
• After all chunks are processed, transactions are deduplicated across adjacent chunks: same date + amount + name appearing in consecutive chunks (index delta ≤ 1) is treated as a chunking artifact and dropped 18.
• Known limitation: legitimate identical transactions at chunk boundaries can be incorrectly removed (acknowledged in comments at 19).

Both extractors normalize transactions to { date, amount, name, category, notes } before returning 20 21.

Key Files#