bankstatementparser 0.0.7__tar.gz → 0.0.8__tar.gz

{bankstatementparser-0.0.7 → bankstatementparser-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bankstatementparser
-Version: 0.0.7
+Version: 0.0.8
 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
@@ -14,12 +14,14 @@ 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: api
 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: fastapi (>=0.115.0) ; extra == "api"
 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)
@@ -29,6 +31,7 @@ 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"
+Requires-Dist: uvicorn (>=0.34.0) ; extra == "api"
 Project-URL: Homepage, https://bankstatementparser.com
 Project-URL: Repository, https://github.com/sebastienrousseau/bankstatementparser
 Description-Content-Type: text/markdown
@@ -39,7 +42,7 @@ Parse bank statements across **six structured formats** (CAMT, PAIN.001, CSV, OF
 
 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&v=0.0.7)](https://pypi.org/project/bankstatementparser/)
+[![PyPI](https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.8)](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)
@@ -92,7 +95,7 @@ Every extracted row carries an immutable `transaction_hash`, an audit-trail `sou
 | **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** | 672 tests, 100% branch coverage, property-based fuzzing with Hypothesis |
+| **100% coverage** | 718 tests, 100% branch coverage, property-based fuzzing with Hypothesis |
 
 ## Requirements
 
@@ -408,12 +411,12 @@ See [`docs/MAPPING.md`](docs/MAPPING.md) for a complete reference of ISO 20022 X
 ## Project Layout
 
 ```text
-bankstatementparser/   Source code (24 modules: deterministic core + hybrid + enrichment subpackages, 100% branch coverage)
+bankstatementparser/   Source code (29 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/                 672 tests (unit, integration, property-based, security, hybrid mocks)
+tests/                 718 tests (unit, integration, property-based, security, hybrid mocks)
 ```
 
 ## Security

{bankstatementparser-0.0.7 → bankstatementparser-0.0.8}/README.md

@@ -4,7 +4,7 @@ Parse bank statements across **six structured formats** (CAMT, PAIN.001, CSV, OF
 
 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&v=0.0.7)](https://pypi.org/project/bankstatementparser/)
+[![PyPI](https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.8)](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)
@@ -57,7 +57,7 @@ Every extracted row carries an immutable `transaction_hash`, an audit-trail `sou
 | **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** | 672 tests, 100% branch coverage, property-based fuzzing with Hypothesis |
+| **100% coverage** | 718 tests, 100% branch coverage, property-based fuzzing with Hypothesis |
 
 ## Requirements
 
@@ -373,12 +373,12 @@ See [`docs/MAPPING.md`](docs/MAPPING.md) for a complete reference of ISO 20022 X
 ## Project Layout
 
 ```text
-bankstatementparser/   Source code (24 modules: deterministic core + hybrid + enrichment subpackages, 100% branch coverage)
+bankstatementparser/   Source code (29 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/                 672 tests (unit, integration, property-based, security, hybrid mocks)
+tests/                 718 tests (unit, integration, property-based, security, hybrid mocks)
 ```
 
 ## Security

bankstatementparser-0.0.8/bankstatementparser/api.py

@@ -0,0 +1,185 @@
+# 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.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Lightweight REST API for the hybrid pipeline.
+
+Finance teams want to POST a file and get JSON back. This module
+wraps :func:`smart_ingest` in a single-file FastAPI app that can be
+run as a microservice:
+
+    pip install 'bankstatementparser[api]'
+    bankstatementparser-api              # starts on :8000
+    bankstatementparser-api --port 9000  # custom port
+
+Or import the app for ASGI deployment::
+
+    from bankstatementparser.api import create_app
+
+    app = create_app()
+    # uvicorn bankstatementparser.api:app --host 0.0.0.0
+
+The API is **stateless** — each ``/ingest`` call processes the
+uploaded file and returns the result as JSON. No database, no
+sessions, no auth (add those in your reverse proxy or wrapper).
+
+Gated behind the ``[api]`` install extra (fastapi + uvicorn).
+"""
+
+from __future__ import annotations
+
+import logging
+import tempfile
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class APIError(RuntimeError):
+    """Raised when the API module can't start."""
+
+
+def create_app(
+    *,
+    title: str = "Bank Statement Parser API",
+    version: str = "0.0.8",
+) -> Any:
+    """Create a FastAPI application wrapping :func:`smart_ingest`.
+
+    Returns:
+        A FastAPI ``app`` instance. Raises :class:`APIError` if
+        FastAPI is not installed.
+    """
+    try:
+        from fastapi import FastAPI, File, UploadFile
+        from fastapi.responses import JSONResponse
+    except ImportError as exc:
+        raise APIError(
+            "FastAPI is required for the REST API. "
+            "Install with: pip install 'bankstatementparser[api]'"
+        ) from exc
+
+    from .hybrid import smart_ingest
+
+    app = FastAPI(title=title, version=version)
+
+    _file_field = File(...)
+
+    @app.post("/ingest")  # type: ignore[untyped-decorator]
+    async def ingest(  # pragma: no cover - async endpoint needs ASGI server
+        file: UploadFile = _file_field,  # noqa: B008
+    ) -> JSONResponse:
+        """Upload a bank statement and get structured JSON back.
+
+        Accepts any format supported by :func:`smart_ingest`:
+        CAMT, PAIN.001, CSV, OFX, QFX, MT940, or PDF. The routing
+        is automatic — deterministic parsers run first, LLM
+        fallback for PDFs.
+
+        Returns the full :class:`IngestResult` as JSON including
+        transactions, verification status, and warnings.
+        """
+        suffix = Path(file.filename or "upload").suffix or ".xml"
+        with tempfile.NamedTemporaryFile(
+            suffix=suffix, delete=False
+        ) as tmp:
+            content = await file.read()
+            tmp.write(content)
+            tmp_path = tmp.name
+
+        try:
+            result = smart_ingest(tmp_path)
+            return JSONResponse(
+                content=_result_to_dict(result),
+                status_code=200,
+            )
+        except Exception as exc:
+            logger.error("Ingest failed: %s", exc)
+            return JSONResponse(
+                content={"error": str(exc)},
+                status_code=422,
+            )
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)
+
+    @app.get("/health")  # type: ignore[untyped-decorator]
+    async def health() -> dict[str, str]:
+        """Health check endpoint."""
+        return {"status": "ok", "version": version}
+
+    return app
+
+
+def _result_to_dict(result: Any) -> dict[str, Any]:
+    """Serialize an IngestResult to a JSON-safe dict."""
+    return {
+        "source_method": result.source_method,
+        "source_format": result.source_format,
+        "transaction_count": len(result.transactions),
+        "transactions": [
+            tx.model_dump(mode="json") for tx in result.transactions
+        ],
+        "verification": _verification_dict(result.verification),
+        "warnings": list(result.warnings),
+    }
+
+
+def _verification_dict(v: Any) -> Optional[dict[str, Any]]:
+    if v is None:
+        return None
+    return {
+        "status": v.status.value,
+        "opening_balance": str(v.opening_balance)
+        if v.opening_balance is not None
+        else None,
+        "closing_balance": str(v.closing_balance)
+        if v.closing_balance is not None
+        else None,
+        "total_credits": str(v.total_credits),
+        "total_debits": str(v.total_debits),
+        "discrepancy": str(v.discrepancy)
+        if v.discrepancy is not None
+        else None,
+        "message": v.message,
+    }
+
+
+def main() -> None:
+    """Console-script entry point for ``bankstatementparser-api``."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Start the Bank Statement Parser REST API."
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Bind address (use 0.0.0.0 for container deployments)",
+    )
+    parser.add_argument(
+        "--port", type=int, default=8000, help="Port"
+    )
+    args = parser.parse_args()
+
+    try:
+        import uvicorn
+    except ImportError as exc:
+        raise APIError(
+            "uvicorn is required to run the API server. "
+            "Install with: pip install 'bankstatementparser[api]'"
+        ) from exc
+
+    app = create_app()  # pragma: no cover - server entrypoint
+    uvicorn.run(app, host=args.host, port=args.port)  # pragma: no cover

{bankstatementparser-0.0.7 → bankstatementparser-0.0.8}/bankstatementparser/enrichment/__init__.py

@@ -46,6 +46,7 @@ deterministic fields.
 
 from __future__ import annotations
 
+from .account_mapper import AccountMapper, AccountRule
 from .categorizer import (
     DEFAULT_CATEGORY_SCHEMA,
     Categorizer,
@@ -54,6 +55,8 @@ from .categorizer import (
 )
 
 __all__ = [
+    "AccountMapper",
+    "AccountRule",
     "DEFAULT_CATEGORY_SCHEMA",
     "Categorizer",
     "CategorizerError",

bankstatementparser-0.0.8/bankstatementparser/enrichment/account_mapper.py

@@ -0,0 +1,150 @@
+# 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.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Configurable account mapping for plaintext-accounting export.
+
+Assigns a destination account to each transaction based on
+description patterns. Designed to pair with the hledger/beancount
+exporter — the categorizer (#44) answers "what category?" while the
+account mapper answers "which ledger account?".
+
+Usage::
+
+    from bankstatementparser.enrichment.account_mapper import (
+        AccountMapper,
+        AccountRule,
+    )
+
+    rules = [
+        AccountRule(pattern="COFFEE|STARBUCKS", account="Expenses:Food:Coffee"),
+        AccountRule(pattern="SALARY", account="Income:Salary"),
+        AccountRule(pattern="RENT", account="Expenses:Housing:Rent"),
+    ]
+    mapper = AccountMapper(rules=rules, default="Expenses:Uncategorized")
+
+    for tx in transactions:
+        account = mapper.map(tx)
+        print(tx.description, "->", account)
+
+Rules are evaluated top-to-bottom; the first match wins. Patterns
+are compiled as case-insensitive regexes against the raw
+description (not the normalized one, so the user sees the patterns
+they'd expect from their bank's actual wording).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Union
+
+from ..transaction_models import Transaction
+
+PathLike = Union[str, Path]
+
+
+@dataclass(frozen=True)
+class AccountRule:
+    """A single pattern → account mapping rule.
+
+    ``pattern`` is a case-insensitive regex matched against the
+    transaction's raw ``description``. ``account`` is the ledger
+    account name to assign when the pattern matches.
+    """
+
+    pattern: str
+    account: str
+
+    def __post_init__(self) -> None:
+        # Validate the regex at construction time so bad patterns
+        # fail loudly, not silently at map time.
+        try:
+            re.compile(self.pattern, re.IGNORECASE)
+        except re.error as exc:
+            raise ValueError(
+                f"Invalid regex in AccountRule: {self.pattern!r}: {exc}"
+            ) from exc
+
+
+@dataclass
+class AccountMapper:
+    """Map transactions to ledger accounts via configurable rules.
+
+    Rules are evaluated top-to-bottom; the first match wins. When
+    no rule matches, ``default`` is returned.
+
+    Args:
+        rules: Ordered list of :class:`AccountRule` instances.
+        default: Fallback account for unmatched transactions.
+    """
+
+    rules: list[AccountRule] = field(default_factory=list)
+    default: str = "Expenses:Uncategorized"
+    _compiled: list[tuple[re.Pattern[str], str]] = field(
+        init=False, default_factory=list, repr=False
+    )
+
+    def __post_init__(self) -> None:
+        self._compiled = [
+            (re.compile(rule.pattern, re.IGNORECASE), rule.account)
+            for rule in self.rules
+        ]
+
+    def map(self, transaction: Transaction) -> str:
+        """Return the ledger account for a single transaction."""
+        desc = transaction.description or ""
+        for compiled_re, account in self._compiled:
+            if compiled_re.search(desc):
+                return account
+        return self.default
+
+    def map_batch(
+        self, transactions: Iterable[Transaction]
+    ) -> list[str]:
+        """Map every transaction in a batch. Returns one account per row."""
+        return [self.map(tx) for tx in transactions]
+
+    @classmethod
+    def from_json(cls, path: PathLike) -> AccountMapper:
+        """Load rules from a JSON file.
+
+        Expected format::
+
+            {
+                "default": "Expenses:Uncategorized",
+                "rules": [
+                    {"pattern": "COFFEE|STARBUCKS", "account": "Expenses:Food:Coffee"},
+                    {"pattern": "SALARY", "account": "Income:Salary"}
+                ]
+            }
+        """
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            raise ValueError("Account mapping JSON must be an object")
+        rules = [
+            AccountRule(
+                pattern=str(r.get("pattern", "")),
+                account=str(r.get("account", "")),
+            )
+            for r in data.get("rules", [])
+            if isinstance(r, dict)
+        ]
+        return cls(
+            rules=rules,
+            default=str(data.get("default", "Expenses:Uncategorized")),
+        )

bankstatementparser-0.0.8/bankstatementparser/export/__init__.py

@@ -0,0 +1,25 @@
+# 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.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Export helpers for plaintext accounting and downstream systems."""
+
+from __future__ import annotations
+
+from .ledger import to_beancount, to_hledger
+
+__all__ = [
+    "to_beancount",
+    "to_hledger",
+]

bankstatementparser-0.0.8/bankstatementparser/export/ledger.py

@@ -0,0 +1,171 @@
+# 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.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Export transactions to hledger and beancount journal formats.
+
+These formats are the two most popular plaintext-accounting file
+formats. Both represent transactions as human-readable text files
+that are version-controlled, diffable, and auditable — a natural
+fit for bank statement data.
+
+Usage::
+
+    from bankstatementparser.export import to_hledger, to_beancount
+
+    journal = to_hledger(transactions, account="Assets:Bank:Checking")
+    Path("journal.ledger").write_text(journal)
+
+    journal = to_beancount(transactions, account="Assets:Bank:Checking")
+    Path("journal.beancount").write_text(journal)
+
+No external dependencies — both functions produce plain strings.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ..transaction_models import Transaction
+
+
+def to_hledger(
+    transactions: Iterable[Transaction],
+    *,
+    account: str = "Assets:Bank:Checking",
+    contra_account: str = "Expenses:Uncategorized",
+    default_currency: str = "EUR",
+) -> str:
+    """Render transactions as an hledger-compatible journal.
+
+    Each transaction produces one journal entry with two postings:
+    one to ``account`` (the bank account) and one to
+    ``contra_account`` (the expense/income bucket). The
+    ``contra_account`` posting has no explicit amount — hledger
+    infers it as the negation.
+
+    If the transaction has a ``category`` field set (from the
+    enrichment module), it replaces ``contra_account`` for that
+    entry.
+
+    Args:
+        transactions: Iterable of :class:`Transaction` objects.
+        account: The bank account name in hledger format.
+        contra_account: Default contra-account for uncategorized
+            transactions.
+        default_currency: Currency code when the transaction has
+            no currency set.
+
+    Returns:
+        A string containing the full journal, ready to write to a
+        ``.ledger`` or ``.journal`` file.
+    """
+    lines: list[str] = []
+    for tx in transactions:
+        date = (
+            tx.booking_date.isoformat()
+            if tx.booking_date is not None
+            else "1970-01-01"
+        )
+        desc = _escape_description(tx.description or "Unknown")
+        currency = tx.currency or default_currency
+        amount = format(tx.amount.normalize(), "f")
+
+        contra = _resolve_contra(tx, contra_account)
+
+        lines.append(f"{date} {desc}")
+        lines.append(f"    {account}    {currency} {amount}")
+        lines.append(f"    {contra}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def to_beancount(
+    transactions: Iterable[Transaction],
+    *,
+    account: str = "Assets:Bank:Checking",
+    contra_account: str = "Expenses:Uncategorized",
+    default_currency: str = "EUR",
+) -> str:
+    """Render transactions as a beancount-compatible journal.
+
+    Beancount uses a slightly different syntax from hledger:
+
+    * The directive is ``txn`` (not implicit).
+    * Amounts appear on both postings (beancount requires explicit
+      amounts unless using ``pad`` directives).
+    * The payee and narration are separate quoted fields.
+
+    Args:
+        transactions: Iterable of :class:`Transaction` objects.
+        account: The bank account name in beancount format.
+        contra_account: Default contra-account.
+        default_currency: Currency code when the transaction has
+            no currency set.
+
+    Returns:
+        A string containing the full journal.
+    """
+    lines: list[str] = []
+    for tx in transactions:
+        date = (
+            tx.booking_date.isoformat()
+            if tx.booking_date is not None
+            else "1970-01-01"
+        )
+        payee = _escape_beancount_string(
+            tx.counterparty or ""
+        )
+        narration = _escape_beancount_string(
+            tx.description or "Unknown"
+        )
+        currency = tx.currency or default_currency
+        amount = format(tx.amount.normalize(), "f")
+        neg_amount = format((-tx.amount).normalize(), "f")
+
+        contra = _resolve_contra(tx, contra_account)
+
+        lines.append(f'{date} txn "{payee}" "{narration}"')
+        lines.append(f"  {account}  {amount} {currency}")
+        lines.append(f"  {contra}  {neg_amount} {currency}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _resolve_contra(
+    tx: Transaction, default: str
+) -> str:
+    """Use the enrichment category as contra-account if available."""
+    category = tx.category
+    if category:
+        safe = category.replace(" ", ":").replace("/", ":")
+        return f"Expenses:{safe}"
+    return default
+
+
+def _escape_description(value: str) -> str:
+    """Sanitize a description for hledger journal format."""
+    return value.replace("\n", " ").replace("\r", "").strip()
+
+
+def _escape_beancount_string(value: str) -> str:
+    """Escape a string for beancount's quoted fields."""
+    return (
+        value.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", " ")
+        .strip()
+    )

{bankstatementparser-0.0.7 → bankstatementparser-0.0.8}/bankstatementparser/hybrid/__init__.py

@@ -38,10 +38,12 @@ from .orchestrator import (
     smart_ingest,
 )
 from .pdf_text import PDFExtractionError, extract_text
+from .scanner import ScanResult, scan_and_ingest
 from .verification import (
     BalanceVerification,
     VerificationStatus,
     verify_balance,
+    verify_balance_multi_currency,
 )
 from .vision import VisionExtractor, VisionExtractorError
 
@@ -53,12 +55,15 @@ __all__ = [
     "LLMExtractorError",
     "OllamaDirectError",
     "PDFExtractionError",
+    "ScanResult",
     "VerificationStatus",
     "VisionExtractor",
     "VisionExtractorError",
     "extract_text",
     "is_ollama_model",
     "ollama_direct_completion",
+    "scan_and_ingest",
     "smart_ingest",
+    "verify_balance_multi_currency",
     "verify_balance",
 ]

bankstatementparser-0.0.8/bankstatementparser/hybrid/scanner.py

@@ -0,0 +1,125 @@
+# 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.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Bulk directory scanner for the hybrid pipeline.
+
+Scans an organized folder tree, runs :func:`smart_ingest` on every
+matching file, and deduplicates across the entire batch via
+:meth:`Deduplicator.dedupe_by_hash`. Designed for the common
+treasury pattern of ``statements/2026/04/*.pdf``.
+
+Usage::
+
+    from bankstatementparser.hybrid.scanner import scan_and_ingest
+
+    batch = scan_and_ingest("statements/", pattern="**/*.pdf")
+    print(f"{len(batch.results)} files, {batch.total_unique} unique tx")
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Union
+
+from ..transaction_deduplicator import Deduplicator
+from ..transaction_models import Transaction
+from .orchestrator import IngestResult, smart_ingest
+
+logger = logging.getLogger(__name__)
+
+PathLike = Union[str, Path]
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    """Output of :func:`scan_and_ingest`."""
+
+    results: tuple[IngestResult, ...]
+    unique_transactions: tuple[Transaction, ...]
+    skipped_hashes: tuple[str, ...]
+    file_count: int
+    total_unique: int
+    total_skipped: int
+
+
+def scan_and_ingest(
+    directory: PathLike,
+    *,
+    pattern: str = "**/*",
+    seen_hashes: Optional[set[str]] = None,
+    extensions: Optional[set[str]] = None,
+) -> ScanResult:
+    """Scan a directory and run :func:`smart_ingest` on every match.
+
+    Args:
+        directory: Root directory to scan.
+        pattern: Glob pattern relative to ``directory``. Defaults
+            to ``**/*`` (recursive, all files).
+        seen_hashes: Optional set of already-ingested hashes for
+            cross-batch dedup. Mutated in-place so callers can
+            persist state.
+        extensions: Allowed file extensions (lowercase, with dot).
+            Defaults to ``{".xml", ".csv", ".ofx", ".qfx",
+            ".mt940", ".sta", ".pdf"}``.
+
+    Returns:
+        A :class:`ScanResult` with all per-file results, the
+        deduplicated transaction list, and the skipped-hash list.
+    """
+    root = Path(directory)
+    if not root.is_dir():
+        raise FileNotFoundError(f"Not a directory: {root}")
+
+    if extensions is None:
+        extensions = {
+            ".xml", ".csv", ".ofx", ".qfx",
+            ".mt940", ".sta", ".pdf",
+        }
+    if seen_hashes is None:
+        seen_hashes = set()
+
+    files = sorted(
+        p
+        for p in root.glob(pattern)
+        if p.is_file() and p.suffix.lower() in extensions
+    )
+
+    all_results: list[IngestResult] = []
+    all_transactions: list[Transaction] = []
+
+    for file_path in files:
+        logger.info("Ingesting %s", file_path)
+        try:
+            result = smart_ingest(file_path)
+            all_results.append(result)
+            all_transactions.extend(result.transactions)
+        except Exception as exc:
+            logger.warning("Failed to ingest %s: %s", file_path, exc)
+
+    dedup = Deduplicator()
+    unique, skipped = dedup.dedupe_by_hash(
+        all_transactions, seen_hashes=seen_hashes
+    )
+
+    return ScanResult(
+        results=tuple(all_results),
+        unique_transactions=tuple(unique),
+        skipped_hashes=tuple(skipped),
+        file_count=len(files),
+        total_unique=len(unique),
+        total_skipped=len(skipped),
+    )

{bankstatementparser-0.0.7 → bankstatementparser-0.0.8}/bankstatementparser/hybrid/verification.py

@@ -22,6 +22,7 @@ the single most important integrity check in the hybrid pipeline.
 
 from __future__ import annotations
 
+from collections import defaultdict
 from collections.abc import Iterable
 from dataclasses import dataclass
 from decimal import Decimal
@@ -131,3 +132,53 @@ def verify_balance(
             f"actual {actual_delta} (off by {discrepancy})"
         ),
     )
+
+
+def verify_balance_multi_currency(
+    transactions: Iterable[Transaction],
+    *,
+    balances: Optional[dict[str, tuple[Decimal, Decimal]]] = None,
+    tolerance: Decimal = Decimal("0.01"),
+) -> dict[str, BalanceVerification]:
+    """Run the Golden Rule **per currency**.
+
+    Multi-currency statements (common in international business
+    banking) mix transactions in different currencies. The single-
+    currency :func:`verify_balance` would always report
+    ``DISCREPANCY`` because it sums GBP and EUR amounts together.
+
+    This function groups transactions by ``Transaction.currency``
+    and runs an independent Golden Rule check for each group.
+
+    Args:
+        transactions: Iterable of normalized transactions.
+        balances: Optional ``{currency: (opening, closing)}`` dict.
+            When ``None``, verification runs with ``FAILED`` status
+            for every currency (no balances provided). When a
+            currency appears in the transactions but not in this
+            dict, its verification is also ``FAILED``.
+        tolerance: Per-currency tolerance. Defaults to one cent.
+
+    Returns:
+        A dict mapping each currency code (uppercase) to its
+        :class:`BalanceVerification`. Transactions with
+        ``currency=None`` are grouped under the key ``"UNKNOWN"``.
+    """
+    balances = balances or {}
+    groups: dict[str, list[Transaction]] = defaultdict(list)
+    for tx in transactions:
+        key = (tx.currency or "UNKNOWN").upper()
+        groups[key].append(tx)
+
+    results: dict[str, BalanceVerification] = {}
+    for currency, txs in sorted(groups.items()):
+        pair = balances.get(currency)
+        opening = pair[0] if pair else None
+        closing = pair[1] if pair else None
+        results[currency] = verify_balance(
+            txs,
+            opening_balance=opening,
+            closing_balance=closing,
+            tolerance=tolerance,
+        )
+    return results

{bankstatementparser-0.0.7 → bankstatementparser-0.0.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "bankstatementparser"
-version = "0.0.7"
+version = "0.0.8"
 description = "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."
 authors = ["Sebastien Rousseau <sebastian.rousseau@gmail.com>"]
 license = "Apache Software License"
@@ -23,6 +23,8 @@ litellm = {version = ">=1.83.0", optional = true}
 pypdf = {version = ">=4.0.0", optional = true}
 pdfplumber = {version = ">=0.11.0", optional = true}
 pypdfium2 = {version = ">=4.30.0", optional = true}
+fastapi = {version = ">=0.115.0", optional = true}
+uvicorn = {version = ">=0.34.0", optional = true}
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0.0"
@@ -39,9 +41,11 @@ hybrid = ["litellm", "pypdf"]
 hybrid-plus = ["litellm", "pypdf", "pdfplumber"]
 hybrid-vision = ["litellm", "pypdf", "pypdfium2"]
 enrichment = ["litellm"]
+api = ["fastapi", "uvicorn"]
 
 [tool.poetry.scripts]
 bankstatementparser = "bankstatementparser.cli:main"
+bankstatementparser-api = "bankstatementparser.api:main"
 
 [build-system]
 requires = ["poetry-core"]
@@ -108,7 +112,7 @@ module = ["polars", "polars.*"]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
-module = ["litellm", "litellm.*", "pypdf", "pypdf.*", "pdfplumber", "pdfplumber.*", "pypdfium2", "pypdfium2.*", "httpx", "httpx.*"]
+module = ["litellm", "litellm.*", "pypdf", "pypdf.*", "pdfplumber", "pdfplumber.*", "pypdfium2", "pypdfium2.*", "httpx", "httpx.*", "fastapi", "fastapi.*", "uvicorn", "uvicorn.*"]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]