PyPI - bankstatementparser - Versions diffs - 0.0.4__tar.gz → 0.0.7__tar.gz - Mend

bankstatementparser 0.0.4tar.gz → 0.0.7tar.gz

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.

Files changed (28) hide show

{bankstatementparser-0.0.4 → bankstatementparser-0.0.7}/PKG-INFO RENAMED Viewed

@@ -1,68 +1,122 @@
 Metadata-Version: 2.4
 Name: bankstatementparser
-Version: 0.0.4
+Version: 0.0.7
 Summary: BankStatementParser is your essential tool for easy bank statement management. Designed with finance and treasury experts in mind, it offers a simple way to handle CAMT (ISO 20022) formats and more. Get quick, accurate insights from your financial data and spend less time on processing. It's the smart, hassle-free way to stay on top of your transactions.
 License: Apache Software License
 License-File: LICENSE
 Author: Sebastien Rousseau
 Author-email: sebastian.rousseau@gmail.com
-Requires-Python: >=3.9
+Requires-Python: >=3.10,<4.0
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: enrichment
+Provides-Extra: hybrid
+Provides-Extra: hybrid-plus
+Provides-Extra: hybrid-vision
 Provides-Extra: polars
 Requires-Dist: defusedxml (>=0.7.1,<0.8.0)
+Requires-Dist: litellm (>=1.83.0) ; extra == "hybrid" or extra == "hybrid-plus" or extra == "hybrid-vision" or extra == "enrichment"
 Requires-Dist: lxml (>=4.9.3)
 Requires-Dist: openpyxl (>=3.1.5,<4.0.0)
 Requires-Dist: pandas (>=2.3.3,<3.0.0)
+Requires-Dist: pdfplumber (>=0.11.0) ; extra == "hybrid-plus"
 Requires-Dist: polars (>=1.32.0,<2.0.0) ; extra == "polars"
 Requires-Dist: pydantic (>=2.11.0,<3.0.0)
+Requires-Dist: pypdf (>=4.0.0) ; extra == "hybrid" or extra == "hybrid-plus" or extra == "hybrid-vision"
+Requires-Dist: pypdfium2 (>=4.30.0) ; extra == "hybrid-vision"
 Project-URL: Homepage, https://bankstatementparser.com
 Project-URL: Repository, https://github.com/sebastienrousseau/bankstatementparser
 Description-Content-Type: text/markdown
 # Bank Statement Parser
-Parse bank statements across six formats — CAMT, PAIN.001, CSV, OFX/QFX, and MT940 — into structured DataFrames. Process ZIP archives safely. Redact PII by default. Stream files of any size.
+Parse bank statements across **six structured formats** (CAMT, PAIN.001, CSV, OFX/QFX, MT940) **and PDFs** — both digital and scanned — into a single unified `Transaction` model. ISO 20022 files take the deterministic path; PDFs fall through to a configurable LLM (Ollama by default, any LiteLLM-supported provider) and finally to a multimodal vision model for scanned/photocopied statements.
-Built for finance teams, treasury analysts, and fintech developers who need reliable, auditable extraction from ISO 20022 and legacy banking formats without sending data to external services.
+Built for finance teams, treasury analysts, and fintech developers who need reliable, auditable extraction across the full spectrum of bank statement formats — without sending data to external services unless they explicitly opt in.
-[![PyPI](https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge)](https://pypi.org/project/bankstatementparser/)
+[![PyPI](https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.7)](https://pypi.org/project/bankstatementparser/)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/bankstatementparser.svg?style=for-the-badge)](https://pypi.org/project/bankstatementparser/)
 [![Codecov](https://img.shields.io/codecov/c/github/sebastienrousseau/bankstatementparser?style=for-the-badge)](https://codecov.io/github/sebastienrousseau/bankstatementparser?branch=main)
 [![License](https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge)](LICENSE)
+## How it works
+`smart_ingest()` routes any input file through the cheapest viable extraction path. Deterministic parsers always run first ($0 cost). Text and vision LLMs are fallbacks for unstandardized PDFs — both are opt-in via separate install extras and can be swapped between any LiteLLM-supported provider (Ollama, Anthropic, OpenAI, Gemini, …).
+```mermaid
+flowchart TD
+    A[smart_ingest&lpar;path&rpar;] --> B{detect_statement_format}
+    B -- CAMT/PAIN/OFX/MT940/CSV --> C[Path A: deterministic parser<br/>$0, fastest]
+    C --> Z[IngestResult<br/>source_method='deterministic']
+    B -- pdf or unknown --> D[pypdf extract_text]
+    D --> E{text len &gt;= 50?}
+    E -- yes --> F[Path B: text-LLM<br/>default ollama/llama3]
+    F --> Y[IngestResult<br/>source_method='llm']
+    E -- no --> G[Path C: vision-LLM<br/>opt-in via BSP_HYBRID_VISION_MODEL]
+    G --> X[IngestResult<br/>source_method='vision']
+    Z --> V[verify_balance<br/>Golden Rule]
+    Y --> V
+    X --> V
+    V --> R[VERIFIED / DISCREPANCY / FAILED]
+```
+Every extracted row carries an immutable `transaction_hash`, an audit-trail `source_method` tag, and (for LLM rows) a `confidence` score — see [Hybrid extraction](#hybrid-extraction-pdfs-included-v005) below for the full surface.
 ## Key Features
 | Feature | Description |
 |---|---|
-| **6 formats** | CAMT.053, PAIN.001, CSV, OFX, QFX, MT940 |
+| **6 structured formats** | CAMT.053, PAIN.001, CSV, OFX, QFX, MT940 |
+| **Hybrid PDF pipeline** *(v0.0.5)* | `smart_ingest()` routes digital PDFs through a text-LLM and scanned PDFs through a multimodal vision model. Deterministic parsers always tried first ($0 cost). |
+| **Local-first LLM** *(v0.0.5)* | Ollama is the default backend; switch to Anthropic, OpenAI, or any LiteLLM provider via `BSP_HYBRID_MODEL`. Vision is opt-in via `BSP_HYBRID_VISION_MODEL` — no surprise downloads. |
+| **Golden Rule verification** *(v0.0.5)* | Every result carries `opening + credits − debits == closing` status: `VERIFIED`, `DISCREPANCY`, or `FAILED`. |
+| **Idempotent dedup** *(v0.0.5)* | Every `Transaction` carries a stable `transaction_hash` (MD5 of date + normalized description + amount). `Deduplicator.dedupe_by_hash()` makes incremental ingestion safe to re-run. |
+| **Categorization** *(v0.0.6)* | `bankstatementparser.enrichment.Categorizer` tags transactions with a pluggable category schema (Plaid 13-category default) and an optional `is_business_expense` flag. Wrapper model — never mutates the original `Transaction`. |
+| **Interactive review** *(v0.0.6)* | `--type review` CLI walks through discrepancies with accept/edit/skip/delete/quit. `IngestResult.to_json()` / `.from_json()` for stable round-trip with embedded audit trail. |
+| **Bounding boxes** *(v0.0.6)* | `Transaction.source_bbox` carries per-row normalized coordinates from the vision path for downstream review UIs. |
+| **Direct Ollama bridge** *(v0.0.7)* | Auto-bypasses the upstream LiteLLM ↔ Ollama hang on long vision prompts. `ollama/minicpm-v` recommended over `ollama/llava` for document OCR. |
+| **Strip mode** *(v0.0.7)* | `VisionExtractor(strip_rows=True)` splits dense pages into overlapping bands for small local models — fixes sign-flip errors and improves accuracy on 15+ row statements. |
 | **Auto-detection** | `detect_statement_format()` identifies the format; `create_parser()` returns the right parser |
-| **Deduplication** | `Deduplicator` detects exact duplicates and suspected matches across sources with explainable confidence scores |
 | **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
 | **Streaming** | `parse_streaming()` at 27,000+ tx/s (CAMT) and 52,000+ tx/s (PAIN.001) with bounded memory |
 | **Parallel** | `parse_files_parallel()` for multi-file batch processing across CPU cores |
 | **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
 | **In-memory parsing** | `from_string()` and `from_bytes()` parse XML without touching disk |
 | **Export** | CSV, JSON, Excel (`.xlsx`), and optional Polars DataFrames |
-| **100% coverage** | 467 tests, 100% branch coverage, property-based fuzzing with Hypothesis |
+| **100% coverage** | 672 tests, 100% branch coverage, property-based fuzzing with Hypothesis |
 ## Requirements
-- Python **3.9** through **3.14**
+- Python **3.10** through **3.14** (Python 3.9 was dropped in v0.0.6 — pin to v0.0.5 if you cannot upgrade your interpreter)
 - Poetry (for local development)
 ## Install
 ```bash
+# Core install — deterministic parsers only (CAMT, PAIN.001, CSV, OFX, QFX, MT940)
 pip install bankstatementparser
+# Add the text-LLM path for digital PDFs (litellm + pypdf)
+pip install 'bankstatementparser[hybrid]'
+# Add higher-fidelity table extraction (adds pdfplumber)
+pip install 'bankstatementparser[hybrid-plus]'
+# Add the multimodal vision path for scanned/photocopied PDFs (adds pypdfium2)
+pip install 'bankstatementparser[hybrid-vision]'
 ```
+The core install has zero AI dependencies. Every `[hybrid*]` extra is opt-in and pure-Python — no `poppler`, no system libraries, no GPU required.
 ### Local Development
 Clone and install on **macOS, Linux, or WSL**:
@@ -74,6 +128,7 @@ python3 -m venv .venv
 source .venv/bin/activate
 pip install poetry
 poetry install --with dev
+make install-hooks   # pre-commit hook runs `make verify` before every commit
 ```
 ## Quick Start
@@ -123,6 +178,37 @@ records = parser.parse()
 Works with `.xml`, `.csv`, `.ofx`, `.qfx`, and `.mt940` files.
+### Hybrid extraction (PDFs included) *(v0.0.5)*
+`smart_ingest()` is the single entry point that routes any file through the cheapest viable extraction path:
+```python
+from bankstatementparser.hybrid import smart_ingest
+# Path A — deterministic parser (free, fastest, $0)
+result = smart_ingest("statement.xml")
+print(result.source_method)         # "deterministic"
+# Path B — text-LLM for digital PDFs (set BSP_HYBRID_MODEL=ollama/llama3)
+result = smart_ingest("statement.pdf")
+print(result.source_method)         # "llm"
+print(result.verification.status)   # VERIFIED | DISCREPANCY | FAILED
+# Path C — multimodal vision for scanned PDFs (set BSP_HYBRID_VISION_MODEL)
+# auto-routed when pypdf cannot extract enough text
+result = smart_ingest("scan.pdf")
+print(result.source_method)         # "vision"
+```
+Every row carries:
+- `source_method` — `"deterministic"`, `"llm"`, or `"vision"` for full audit provenance
+- `transaction_hash` — MD5 fingerprint of `date | normalized_description | amount`, ready for idempotent re-ingestion
+- `confidence` — float between 0 and 1 for LLM rows, `None` for deterministic
+- `raw_source_text` — best-effort source-text slice for the v0.0.6 review-mode UI
+A complete walkthrough with synthetic UK-bank PDFs, mock vs. live mode, and a Mermaid flow diagram lives in [`examples/hybrid/README.md`](examples/hybrid/README.md).
 ### Parse from memory (no disk I/O)
 ```python
@@ -210,18 +296,28 @@ Uses `ProcessPoolExecutor` to bypass the GIL. Each file is parsed in its own wor
 ## Command Line
+After installation a `bankstatementparser` console script is available on `PATH`:
 ```bash
 # Parse and display
-python -m bankstatementparser.cli --type camt --input statement.xml
+bankstatementparser --type camt --input statement.xml
 # Export to CSV
-python -m bankstatementparser.cli --type camt --input statement.xml --output transactions.csv
+bankstatementparser --type camt --input statement.xml --output transactions.csv
 # Stream with PII visible
-python -m bankstatementparser.cli --type camt --input statement.xml --streaming --show-pii
+bankstatementparser --type camt --input statement.xml --streaming --show-pii
+# v0.0.5 — hybrid pipeline (auto-routes deterministic / text-LLM / vision)
+bankstatementparser --type ingest --input statement.pdf
+bankstatementparser --type ingest --input statement.pdf --output ledger.csv
+# v0.0.6 — interactive review of saved IngestResult JSON
+bankstatementparser --type review --input result.json
+bankstatementparser --type review --input result.json --output reviewed.json
 ```
-Supports `--type camt` and `--type pain001`.
+Supports `--type camt`, `--type pain001`, `--type ingest` (v0.0.5), and `--type review` (v0.0.6). The `python -m bankstatementparser.cli ...` invocation form continues to work for parity with older releases.
 ## Deduplication
@@ -270,7 +366,9 @@ Install with `pip install bankstatementparser[polars]`.
 ## Examples
-See [`examples/`](examples/README.md) for 14 runnable scripts:
+See [`examples/`](examples/README.md) for 22 runnable scripts (14 deterministic + 8 hybrid):
+### Deterministic parsers
 | Example | What it demonstrates |
 |---|---|
@@ -289,6 +387,20 @@ See [`examples/`](examples/README.md) for 14 runnable scripts:
 | `compatibility_wrappers.py` | Legacy API wrappers |
 | `cli_examples.sh` | CLI commands for CAMT and PAIN.001 |
+### Hybrid pipeline *(v0.0.5)*
+| Example | What it demonstrates |
+|---|---|
+| `hybrid/generate_sample_pdfs.py` | Produce reproducible synthetic UK-bank PDFs (digital + scanned) |
+| `hybrid/01_smart_ingest_deterministic.py` | Path A — `smart_ingest()` against a CAMT.053 fixture, $0 cost |
+| `hybrid/02_smart_ingest_text_llm.py` | Path B — text-LLM extraction from a digital PDF (mock or live Ollama) |
+| `hybrid/03_smart_ingest_vision.py` | Path C — multimodal vision extraction with `LOW_TEXT_DENSITY` auto-routing |
+| `hybrid/04_golden_rule.py` | All three `verify_balance()` outcomes |
+| `hybrid/05_dedupe_recurring.py` | `normalize_description()` + `dedupe_by_hash()` for idempotent batching |
+| `hybrid/06_cli_walkthrough.sh` | Four flavours of the new `--type ingest` CLI subcommand |
+See [`examples/hybrid/README.md`](examples/hybrid/README.md) for the full walkthrough including a Mermaid flow diagram, the cross-platform verification matrix, and the Ollama smoke-test results.
 ## XML Tag Mapping
 See [`docs/MAPPING.md`](docs/MAPPING.md) for a complete reference of ISO 20022 XML tags to DataFrame columns across all six formats. Use this when integrating with ERP systems or building reconciliation pipelines.
@@ -296,11 +408,12 @@ See [`docs/MAPPING.md`](docs/MAPPING.md) for a complete reference of ISO 20022 X
 ## Project Layout
 ```text
-bankstatementparser/   Source code (13 modules, 100% branch coverage)
-docs/compliance/       ISO 13485 validation, risk register, traceability
-examples/              14 runnable example scripts
+bankstatementparser/   Source code (24 modules: deterministic core + hybrid + enrichment subpackages, 100% branch coverage)
+bankstatementparser/hybrid/   PDF pipeline: orchestrator, llm_extractor, vision, pdf_text, prompts, verification, ollama_direct
+docs/compliance/       ISO 13485 validation, risk register, traceability matrix
+examples/              14 deterministic + 8 hybrid runnable example scripts
 scripts/               SBOM generation, checksums, signature verification
-tests/                 467 tests (unit, integration, property-based, security)
+tests/                 672 tests (unit, integration, property-based, security, hybrid mocks)
 ```
 ## Security

{bankstatementparser-0.0.4 → bankstatementparser-0.0.7}/README.md RENAMED Viewed

@@ -1,40 +1,87 @@
 # Bank Statement Parser
-Parse bank statements across six formats — CAMT, PAIN.001, CSV, OFX/QFX, and MT940 — into structured DataFrames. Process ZIP archives safely. Redact PII by default. Stream files of any size.
+Parse bank statements across **six structured formats** (CAMT, PAIN.001, CSV, OFX/QFX, MT940) **and PDFs** — both digital and scanned — into a single unified `Transaction` model. ISO 20022 files take the deterministic path; PDFs fall through to a configurable LLM (Ollama by default, any LiteLLM-supported provider) and finally to a multimodal vision model for scanned/photocopied statements.
-Built for finance teams, treasury analysts, and fintech developers who need reliable, auditable extraction from ISO 20022 and legacy banking formats without sending data to external services.
+Built for finance teams, treasury analysts, and fintech developers who need reliable, auditable extraction across the full spectrum of bank statement formats — without sending data to external services unless they explicitly opt in.
-[![PyPI](https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge)](https://pypi.org/project/bankstatementparser/)
+[![PyPI](https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.7)](https://pypi.org/project/bankstatementparser/)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/bankstatementparser.svg?style=for-the-badge)](https://pypi.org/project/bankstatementparser/)
 [![Codecov](https://img.shields.io/codecov/c/github/sebastienrousseau/bankstatementparser?style=for-the-badge)](https://codecov.io/github/sebastienrousseau/bankstatementparser?branch=main)
 [![License](https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge)](LICENSE)
+## How it works
+`smart_ingest()` routes any input file through the cheapest viable extraction path. Deterministic parsers always run first ($0 cost). Text and vision LLMs are fallbacks for unstandardized PDFs — both are opt-in via separate install extras and can be swapped between any LiteLLM-supported provider (Ollama, Anthropic, OpenAI, Gemini, …).
+```mermaid
+flowchart TD
+    A[smart_ingest&lpar;path&rpar;] --> B{detect_statement_format}
+    B -- CAMT/PAIN/OFX/MT940/CSV --> C[Path A: deterministic parser<br/>$0, fastest]
+    C --> Z[IngestResult<br/>source_method='deterministic']
+    B -- pdf or unknown --> D[pypdf extract_text]
+    D --> E{text len &gt;= 50?}
+    E -- yes --> F[Path B: text-LLM<br/>default ollama/llama3]
+    F --> Y[IngestResult<br/>source_method='llm']
+    E -- no --> G[Path C: vision-LLM<br/>opt-in via BSP_HYBRID_VISION_MODEL]
+    G --> X[IngestResult<br/>source_method='vision']
+    Z --> V[verify_balance<br/>Golden Rule]
+    Y --> V
+    X --> V
+    V --> R[VERIFIED / DISCREPANCY / FAILED]
+```
+Every extracted row carries an immutable `transaction_hash`, an audit-trail `source_method` tag, and (for LLM rows) a `confidence` score — see [Hybrid extraction](#hybrid-extraction-pdfs-included-v005) below for the full surface.
 ## Key Features
 | Feature | Description |
 |---|---|
-| **6 formats** | CAMT.053, PAIN.001, CSV, OFX, QFX, MT940 |
+| **6 structured formats** | CAMT.053, PAIN.001, CSV, OFX, QFX, MT940 |
+| **Hybrid PDF pipeline** *(v0.0.5)* | `smart_ingest()` routes digital PDFs through a text-LLM and scanned PDFs through a multimodal vision model. Deterministic parsers always tried first ($0 cost). |
+| **Local-first LLM** *(v0.0.5)* | Ollama is the default backend; switch to Anthropic, OpenAI, or any LiteLLM provider via `BSP_HYBRID_MODEL`. Vision is opt-in via `BSP_HYBRID_VISION_MODEL` — no surprise downloads. |
+| **Golden Rule verification** *(v0.0.5)* | Every result carries `opening + credits − debits == closing` status: `VERIFIED`, `DISCREPANCY`, or `FAILED`. |
+| **Idempotent dedup** *(v0.0.5)* | Every `Transaction` carries a stable `transaction_hash` (MD5 of date + normalized description + amount). `Deduplicator.dedupe_by_hash()` makes incremental ingestion safe to re-run. |
+| **Categorization** *(v0.0.6)* | `bankstatementparser.enrichment.Categorizer` tags transactions with a pluggable category schema (Plaid 13-category default) and an optional `is_business_expense` flag. Wrapper model — never mutates the original `Transaction`. |
+| **Interactive review** *(v0.0.6)* | `--type review` CLI walks through discrepancies with accept/edit/skip/delete/quit. `IngestResult.to_json()` / `.from_json()` for stable round-trip with embedded audit trail. |
+| **Bounding boxes** *(v0.0.6)* | `Transaction.source_bbox` carries per-row normalized coordinates from the vision path for downstream review UIs. |
+| **Direct Ollama bridge** *(v0.0.7)* | Auto-bypasses the upstream LiteLLM ↔ Ollama hang on long vision prompts. `ollama/minicpm-v` recommended over `ollama/llava` for document OCR. |
+| **Strip mode** *(v0.0.7)* | `VisionExtractor(strip_rows=True)` splits dense pages into overlapping bands for small local models — fixes sign-flip errors and improves accuracy on 15+ row statements. |
 | **Auto-detection** | `detect_statement_format()` identifies the format; `create_parser()` returns the right parser |
-| **Deduplication** | `Deduplicator` detects exact duplicates and suspected matches across sources with explainable confidence scores |
 | **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
 | **Streaming** | `parse_streaming()` at 27,000+ tx/s (CAMT) and 52,000+ tx/s (PAIN.001) with bounded memory |
 | **Parallel** | `parse_files_parallel()` for multi-file batch processing across CPU cores |
 | **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
 | **In-memory parsing** | `from_string()` and `from_bytes()` parse XML without touching disk |
 | **Export** | CSV, JSON, Excel (`.xlsx`), and optional Polars DataFrames |
-| **100% coverage** | 467 tests, 100% branch coverage, property-based fuzzing with Hypothesis |
+| **100% coverage** | 672 tests, 100% branch coverage, property-based fuzzing with Hypothesis |
 ## Requirements
-- Python **3.9** through **3.14**
+- Python **3.10** through **3.14** (Python 3.9 was dropped in v0.0.6 — pin to v0.0.5 if you cannot upgrade your interpreter)
 - Poetry (for local development)
 ## Install
 ```bash
+# Core install — deterministic parsers only (CAMT, PAIN.001, CSV, OFX, QFX, MT940)
 pip install bankstatementparser
+# Add the text-LLM path for digital PDFs (litellm + pypdf)
+pip install 'bankstatementparser[hybrid]'
+# Add higher-fidelity table extraction (adds pdfplumber)
+pip install 'bankstatementparser[hybrid-plus]'
+# Add the multimodal vision path for scanned/photocopied PDFs (adds pypdfium2)
+pip install 'bankstatementparser[hybrid-vision]'
 ```
+The core install has zero AI dependencies. Every `[hybrid*]` extra is opt-in and pure-Python — no `poppler`, no system libraries, no GPU required.
 ### Local Development
 Clone and install on **macOS, Linux, or WSL**:
@@ -46,6 +93,7 @@ python3 -m venv .venv
 source .venv/bin/activate
 pip install poetry
 poetry install --with dev
+make install-hooks   # pre-commit hook runs `make verify` before every commit
 ```
 ## Quick Start
@@ -95,6 +143,37 @@ records = parser.parse()
 Works with `.xml`, `.csv`, `.ofx`, `.qfx`, and `.mt940` files.
+### Hybrid extraction (PDFs included) *(v0.0.5)*
+`smart_ingest()` is the single entry point that routes any file through the cheapest viable extraction path:
+```python
+from bankstatementparser.hybrid import smart_ingest
+# Path A — deterministic parser (free, fastest, $0)
+result = smart_ingest("statement.xml")
+print(result.source_method)         # "deterministic"
+# Path B — text-LLM for digital PDFs (set BSP_HYBRID_MODEL=ollama/llama3)
+result = smart_ingest("statement.pdf")
+print(result.source_method)         # "llm"
+print(result.verification.status)   # VERIFIED | DISCREPANCY | FAILED
+# Path C — multimodal vision for scanned PDFs (set BSP_HYBRID_VISION_MODEL)
+# auto-routed when pypdf cannot extract enough text
+result = smart_ingest("scan.pdf")
+print(result.source_method)         # "vision"
+```
+Every row carries:
+- `source_method` — `"deterministic"`, `"llm"`, or `"vision"` for full audit provenance
+- `transaction_hash` — MD5 fingerprint of `date | normalized_description | amount`, ready for idempotent re-ingestion
+- `confidence` — float between 0 and 1 for LLM rows, `None` for deterministic
+- `raw_source_text` — best-effort source-text slice for the v0.0.6 review-mode UI
+A complete walkthrough with synthetic UK-bank PDFs, mock vs. live mode, and a Mermaid flow diagram lives in [`examples/hybrid/README.md`](examples/hybrid/README.md).
 ### Parse from memory (no disk I/O)
 ```python
@@ -182,18 +261,28 @@ Uses `ProcessPoolExecutor` to bypass the GIL. Each file is parsed in its own wor
 ## Command Line
+After installation a `bankstatementparser` console script is available on `PATH`:
 ```bash
 # Parse and display
-python -m bankstatementparser.cli --type camt --input statement.xml
+bankstatementparser --type camt --input statement.xml
 # Export to CSV
-python -m bankstatementparser.cli --type camt --input statement.xml --output transactions.csv
+bankstatementparser --type camt --input statement.xml --output transactions.csv
 # Stream with PII visible
-python -m bankstatementparser.cli --type camt --input statement.xml --streaming --show-pii
+bankstatementparser --type camt --input statement.xml --streaming --show-pii
+# v0.0.5 — hybrid pipeline (auto-routes deterministic / text-LLM / vision)
+bankstatementparser --type ingest --input statement.pdf
+bankstatementparser --type ingest --input statement.pdf --output ledger.csv
+# v0.0.6 — interactive review of saved IngestResult JSON
+bankstatementparser --type review --input result.json
+bankstatementparser --type review --input result.json --output reviewed.json
 ```
-Supports `--type camt` and `--type pain001`.
+Supports `--type camt`, `--type pain001`, `--type ingest` (v0.0.5), and `--type review` (v0.0.6). The `python -m bankstatementparser.cli ...` invocation form continues to work for parity with older releases.
 ## Deduplication
@@ -242,7 +331,9 @@ Install with `pip install bankstatementparser[polars]`.
 ## Examples
-See [`examples/`](examples/README.md) for 14 runnable scripts:
+See [`examples/`](examples/README.md) for 22 runnable scripts (14 deterministic + 8 hybrid):
+### Deterministic parsers
 | Example | What it demonstrates |
 |---|---|
@@ -261,6 +352,20 @@ See [`examples/`](examples/README.md) for 14 runnable scripts:
 | `compatibility_wrappers.py` | Legacy API wrappers |
 | `cli_examples.sh` | CLI commands for CAMT and PAIN.001 |
+### Hybrid pipeline *(v0.0.5)*
+| Example | What it demonstrates |
+|---|---|
+| `hybrid/generate_sample_pdfs.py` | Produce reproducible synthetic UK-bank PDFs (digital + scanned) |
+| `hybrid/01_smart_ingest_deterministic.py` | Path A — `smart_ingest()` against a CAMT.053 fixture, $0 cost |
+| `hybrid/02_smart_ingest_text_llm.py` | Path B — text-LLM extraction from a digital PDF (mock or live Ollama) |
+| `hybrid/03_smart_ingest_vision.py` | Path C — multimodal vision extraction with `LOW_TEXT_DENSITY` auto-routing |
+| `hybrid/04_golden_rule.py` | All three `verify_balance()` outcomes |
+| `hybrid/05_dedupe_recurring.py` | `normalize_description()` + `dedupe_by_hash()` for idempotent batching |
+| `hybrid/06_cli_walkthrough.sh` | Four flavours of the new `--type ingest` CLI subcommand |
+See [`examples/hybrid/README.md`](examples/hybrid/README.md) for the full walkthrough including a Mermaid flow diagram, the cross-platform verification matrix, and the Ollama smoke-test results.
 ## XML Tag Mapping
 See [`docs/MAPPING.md`](docs/MAPPING.md) for a complete reference of ISO 20022 XML tags to DataFrame columns across all six formats. Use this when integrating with ERP systems or building reconciliation pipelines.
@@ -268,11 +373,12 @@ See [`docs/MAPPING.md`](docs/MAPPING.md) for a complete reference of ISO 20022 X
 ## Project Layout
 ```text
-bankstatementparser/   Source code (13 modules, 100% branch coverage)
-docs/compliance/       ISO 13485 validation, risk register, traceability
-examples/              14 runnable example scripts
+bankstatementparser/   Source code (24 modules: deterministic core + hybrid + enrichment subpackages, 100% branch coverage)
+bankstatementparser/hybrid/   PDF pipeline: orchestrator, llm_extractor, vision, pdf_text, prompts, verification, ollama_direct
+docs/compliance/       ISO 13485 validation, risk register, traceability matrix
+examples/              14 deterministic + 8 hybrid runnable example scripts
 scripts/               SBOM generation, checksums, signature verification
-tests/                 467 tests (unit, integration, property-based, security)
+tests/                 672 tests (unit, integration, property-based, security, hybrid mocks)
 ```
 ## Security

{bankstatementparser-0.0.4 → bankstatementparser-0.0.7}/bankstatementparser/__init__.py RENAMED Viewed

@@ -1,4 +1,4 @@
-# Copyright (C) 2023 Sebastien Rousseau.
+# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -46,7 +46,7 @@ from .transaction_deduplicator import (
     ExactDuplicateGroup,
     MatchGroup,
 )
-from .transaction_models import Transaction
+from .transaction_models import BoundingBox, Transaction
 from .zip_security import (
     ZipSecurityError,
     ZipXMLSource,
@@ -67,6 +67,7 @@ __all__ = [
     "Pain001Parser",
     "Pain001ParseError",
     "ParserError",
+    "BoundingBox",
     "Transaction",
     "Deduplicator",
     "DeduplicationResult",

{bankstatementparser-0.0.4 → bankstatementparser-0.0.7}/bankstatementparser/bank_statement_parsers.py RENAMED Viewed

@@ -1,4 +1,4 @@
-# Copyright (C) 2023 Sebastien Rousseau.
+# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{bankstatementparser-0.0.4 → bankstatementparser-0.0.7}/bankstatementparser/base_parser.py RENAMED Viewed

@@ -1,4 +1,4 @@
-# Copyright (C) 2023 Sebastien Rousseau.
+# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{bankstatementparser-0.0.4 → bankstatementparser-0.0.7}/bankstatementparser/camt_parser.py RENAMED Viewed

@@ -1,4 +1,4 @@
-# Copyright (C) 2023 Sebastien Rousseau.
+# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -546,6 +546,7 @@ class CamtParser(BankStatementParser):
                 booking_dates,
                 debtor_addresses,
                 creditor_addresses,
+                strict=False,
             )
         ):
             # Apply debit sign adjustment

bankstatementparser 0.0.4__tar.gz → 0.0.7__tar.gz

bankstatementparser 0.0.4tar.gz → 0.0.7tar.gz