Często zadawane pytania

Prywatność danych i zgodność

Czy jakiekolwiek dane opuszczają moją infrastrukturę?

Nie — nawet przy ekstrakcji PDF. Bank Statement Parser działa jako biblioteka bezstanowa. Całe przetwarzanie — parsowanie, redakcja PII, ekstrakcja archiwów — odbywa się w lokalnej pamięci środowiska wykonawczego. Hybrydowy pipeline PDF używa Ollama do lokalnej inferencji LLM — bez chmurowych API. Parsery XML są zabezpieczone przez no_network=True, blokując cały dostęp wychodzący na poziomie parsera. Dane finansowe nigdy nie opuszczają środowiska.

Jak działa redakcja PII?

Wrażliwe pola są maskowane, zanim dotrą do logiki aplikacji. Parser identyfikuje nazwiska dłużników, nazwy wierzycieli, numery IBAN i adresy pocztowe, zastępując je wartością ***REDACTED*** w wynikach konsolowych i trybie streaming.

• Redakcja jest domyślnie włączona w wynikach CLI i trybie streaming.
• Eksporty plików (CSV, JSON, Excel) zachowują niezredagowane dane do dalszego przetwarzania.
• Włączenie pełnych danych za pomocą --show-pii w CLI lub redact_pii=False w API.

Czy proces ekstrakcji jest deterministyczny?

Tak, dla formatów strukturalnych — bajt po bajcie identyczne wyniki przy każdym uruchomieniu. Dla tego samego pliku wejściowego parsery deterministyczne (CAMT, PAIN.001, CSV, OFX, QFX, MT940) dają za każdym razem ten sam wynik. Żadnej losowości, żadnej inferencji modelu, żadnego próbkowania heurystycznego.

Dla hybrydowego pipeline PDF, ścieżki ekstrakcji oparte na LLM mogą dać drobne różnice między uruchomieniami. Dlatego każda ekstrakcja PDF jest weryfikowana za pomocą Golden Rule (opening + credits − debits == closing), a oznaczone rozbieżności można przeglądać interaktywnie.

CI wymusza determinizm za pomocą 718 testów przy 100% pokryciu gałęzi, w tym fuzzowania opartego na właściwościach przez Hypothesis.

Jakie standardy zgodności spełnia projekt?

Projekt prowadzi dokumentację zgodną z ISO 13485 z pełną identyfikowalnością:

• Ilościowy Rejestr Ryzyka z punktacją dotkliwości/prawdopodobieństwa i oceną ryzyka resztkowego.
• Plan weryfikacji i walidacji z 19 bramkowanymi etapami w 5 fazach.
• Procedura kontroli zmian z oceną wpływu i protokołami wycofywania.
• Rejestr SOUP obejmujący wszystkie zależności z poziomami ryzyka i śledzeniem EOL.
• Macierz identyfikowalności mapująca dane wejściowe projektu do implementacji i weryfikacji.

Każde wydanie zawiera CycloneDX SBOM, sumy kontrolne SHA-256 i poświadczenie pochodzenia kompilacji GitHub.

Wydajność i skalowalność

Jak szybki jest Bank Statement Parser?

Progi wydajności są weryfikowane w CI przy każdym commit:

Szybkość ekstrakcji PDF zależy od ścieżki routingu: deterministyczna (poniżej sekundy), text-LLM (sekundy), vision-LLM (sekundy na stronę).

Jak obsługiwane są duże pliki?

Streaming z ograniczoną pamięcią — testowane przy 50 000 transakcji na plik. Użyj parse_streaming() do przyrostowego przetwarzania plików XML. Każda transakcja jest zwracana jako słownik; elementy są czyszczone po przetworzeniu, co zapobiega wzrostowi pamięci. Pamięć nie rośnie z rozmiarem pliku — test 50 tys. transakcji (25+ MB) zużywa mniej niż 2x pamięci testu 10 tys. transakcji.

Dla plików powyżej 50 MB (np. partie PAIN.001 host-to-host ze 100 tys.+ płatności) parser przesyła dane przez plik tymczasowy z usuwaniem przestrzeni nazw fragmentami — pełny dokument nigdy nie jest ładowany do pamięci.

Jak bezpiecznie przetwarzane są archiwa ZIP?

iter_secure_xml_entries() sprawdza każdy element przed ekstrakcją:

• Limit rozmiaru wpisu (domyślnie 10 MB na wpis)
• Limit całkowitego rozmiaru nieskompresowanego (domyślnie 50 MB)
• Limit współczynnika kompresji (domyślnie 100:1) zapobiegający bombom ZIP
• Odrzucanie wpisów zaszyfrowanych

Żaden plik nie jest zapisywany na dysku. Bajty XML przesyłane są bezpośrednio do parsera przez from_bytes().

Czy mogę parsować wiele plików równolegle?

Tak. Użyj parse_files_parallel(), który rozdziela pracę na ProcessPoolExecutor:

from bankstatementparser import parse_files_parallel

results = parse_files_parallel([
    "statements/jan.xml",
    "statements/feb.xml",
    "statements/mar.xml",
])
for r in results:
    print(r.path, r.status, len(r.transactions), "rows")

Dla masowego przetwarzania PDF użyj scan_and_ingest(), który przetwarza całe drzewa folderów z automatyczną deduplikacją.

Obsługiwane formaty

Jakie formaty wyciągów bankowych są obsługiwane?

Format	Standard	Typy plików	Parser/metoda
CAMT.053	ISO 20022 Bank-to-Customer Statement	.xml	CamtParser
PAIN.001	ISO 20022 Credit Transfer Initiation	.xml	Pain001Parser
CSV	Ogólne eksporty bankowe	.csv	CsvStatementParser
OFX	Open Financial Exchange	.ofx	OfxParser
QFX	Quicken Financial Exchange	.qfx	QfxParser
MT940	Standard SWIFT	.mt940, .sta	Mt940Parser
PDF	Wyciągi cyfrowe i zeskanowane	.pdf	smart_ingest()

Jak działa hybrydowy pipeline PDF?

Hybrydowy pipeline (od wersji 0.0.5+) inteligentnie kieruje pliki PDF przez trzy ścieżki ekstrakcji:

• Ścieżka A (deterministyczna): Ustrukturyzowane tabele PDF parsowane bezpośrednio — bezpłatnie, najszybciej, bez potrzeby LLM.
• Ścieżka B (Text-LLM): Cyfrowe pliki PDF ze złożonymi układami przetwarzane przez lokalny LLM (LiteLLM/Ollama).
• Ścieżka C (Vision-LLM): Zeskanowane lub skserowane wyciągi przetwarzane przez multimodalne modele wizyjne.

Każda ekstrakcja jest weryfikowana za pomocą Golden Rule (opening + credits − debits == closing). Rozbieżności można przeglądać interaktywnie za pomocą --type review.

Czy parser obsługuje specyficzne dla banku dialekty CAMT.053?

Tak — z założenia niezależny od przestrzeni nazw. Parser usuwa przestrzenie nazw XML przed przetworzeniem, obsługując dowolny wariant CAMT.053 (camt.053.001.02, camt.053.001.04 lub własnościowe wrappery bankowe) bez konfiguracji specyficznej dla przestrzeni nazw. Zapytania XPath celują w strukturę elementów, nie w URI przestrzeni nazw.

Dla banków, które pakują CAMT w niestandardową kopertę, użyj from_string() lub from_bytes(), aby podać bezpośrednio dokument wewnętrzny.

Czy mogę zmapować niestandardowe nagłówki kolumn CSV na standardowy schemat?

Tak — automatyczna normalizacja, zero konfiguracji. CsvStatementParser rozpoznaje typowe odmiany nagłówków: "Date", "Transaction Date", "Booking Date" — wszystkie mapowane na pole date. "Amount", "Value", "Sum" mapowane na amount. Rozdzielone kolumny uznań/obciążeń (np. "Credit" i "Debit") są automatycznie wykrywane i łączone w jedną kwotę ze znakiem.

Jaki jest format wyjściowy?

Wszystkie parsery tworzą ustandaryzowane pandas DataFrames ze spójnymi typami kolumn:

Format	Kluczowe kolumny
CAMT	Amount, Currency, DrCr, Debtor, Creditor, Reference, ValDt, BookgDt, AccountId
PAIN.001	PmtInfId, PmtMtd, InstdAmt, Currency, CdtrNm, EndToEndId, MsgId, CreDtTm, NbOfTxs
CSV/OFX/QFX/MT940	date, description, amount (znormalizowane)

Można też eksportować do CSV, JSON, Excel, Polars DataFrames, hledger lub formatu dziennika beancount.

Funkcje PDF i LLM

Jakie modele LLM obsługuje hybrydowy pipeline?

Pipeline używa LiteLLM jako warstwy abstrakcji modeli z bezpośrednim mostem do Ollama dla promptów wizyjnych. Zalecane modele:

• Ekstrakcja tekstu: Dowolny model kompatybilny z LiteLLM (lokalny lub zdalny).
• Ekstrakcja wizualna: ollama/minicpm-v (zalecany) dla zeskanowanych PDF.
• Kategoryzacja: Dowolny model kompatybilny z LiteLLM.

Wszystkie modele mogą działać w 100% lokalnie przez Ollama — nie są wymagane klucze API.

Czym jest weryfikacja Golden Rule?

Każda ekstrakcja PDF jest weryfikowana równaniem: opening balance + credits − debits == closing balance. Wyniki są oznaczane jako:

• VERIFIED: Salda zgadzają się dokładnie.
• DISCREPANCY: Salda się nie zgadzają — zalecany przegląd.
• FAILED: Weryfikacja nie mogła zostać przeprowadzona (brak danych o saldzie).

Czy mogę automatycznie kategoryzować transakcje?

Tak. Moduł wzbogacania (od wersji 0.0.6+) zapewnia kategoryzację transakcji z użyciem LLM:

from bankstatementparser.enrichment import Categorizer

categorizer = Categorizer()
enriched = categorizer.categorize_batch(transactions)

Domyślny schemat używa 13 kategorii kompatybilnych z Plaid. Można dostarczyć własny schemat kategorii.

Czy mogę eksportować do hledger lub beancount?

Tak (od wersji 0.0.8+). Eksport transakcji do formatów dziennika plaintext-accounting z mapowaniem kont:

from bankstatementparser.export import to_hledger, to_beancount

journal = to_hledger(transactions, account="Assets:Bank:Checking")

Przepływy pracy skarbca

Jak parser obsługuje wyciągi wielowalutowe?

Każda transakcja zachowuje swoją pierwotną walutę — bez ukrytej konwersji. Pole Currency jest wyodrębniane z atrybutu XML Ccy dla każdej transakcji. Wyciągi wielowalutowe pozostają bez zmian. Metoda get_account_balances() zwraca salda otwarcia i zamknięcia konta z oryginalnymi kodami walut.

Od wersji 0.0.8, verify_balance_multi_currency() grupuje transakcje według waluty i uruchamia Golden Rule niezależnie dla każdej grupy — przydatne dla kont z wieloma walutami.

Czy parser obsługuje zarówno formaty wychodzące, jak i przychodzące?

Tak. Pain001Parser obsługuje pliki ISO 20022 PAIN.001 inicjacji przelewów (płatności wychodzące). CamtParser obsługuje pliki wyciągów CAMT.053 bank-do-klienta (raporty przychodzące). Oba obsługują streaming, redakcję PII oraz eksport do CSV, JSON, Excel, hledger i beancount. Użyj detect_statement_format(), aby automatycznie zidentyfikować format.

Co się stanie, jeśli wpis transakcji jest zniekształcony?

Zachowanie zależy od trybu parsowania:

• parse() (tryb wsadowy) -- Zniekształcone wpisy bez wymaganych pól (Amount, Currency lub CdtDbtInd) są pomijane z ostrzeżeniem w logu. Reszta wyciągu jest parsowana normalnie.
• parse_streaming() (tryb streaming) -- Błędy parsowania propagowane są natychmiast jako wyjątki. Brak cichej utraty danych. To zachowanie fail-fast jest zamierzone w przepływach pracy finansowych, gdzie każda transakcja musi zostać rozliczona.
• smart_ingest() (hybrydowy PDF) -- Błędy ekstrakcji są zapisywane w IngestResult ze statusem weryfikacji, umożliwiając interaktywny przegląd.

Jak działa deduplikacja?

Każdej transakcji przypisywany jest idempotentny transaction_hash (odcisk MD5) oparty na kluczowych polach. Umożliwia to bezpieczny przyrostowy import — ponowne przetworzenie tego samego pliku generuje te same hash, więc duplikaty są wykrywane automatycznie.

from bankstatementparser import CamtParser, Deduplicator

parser = CamtParser("statement.xml")
dedup = Deduplicator()
result = dedup.deduplicate(dedup.from_dataframe(parser.parse()))

print(f"Unique: {len(result.unique_transactions)}")
print(f"Exact duplicates: {len(result.exact_duplicates)}")
print(f"Suspected matches: {len(result.suspected_matches)}")

Instalacja i kompatybilność

Jak zainstalować Bank Statement Parser?

# Core install (deterministic parsers only)
pip install bankstatementparser

# PDF hybrid pipeline
pip install 'bankstatementparser[hybrid]'         # Text-LLM path
pip install 'bankstatementparser[hybrid-vision]'   # Vision-LLM path

# Extras
pip install 'bankstatementparser[enrichment]'      # Transaction categorisation
pip install 'bankstatementparser[api]'             # REST API microservice
pip install 'bankstatementparser[polars]'          # Polars DataFrame support

Które wersje Pythona są obsługiwane?

Python od 3.10 do 3.14. Wsparcie dla Pythona 3.9 zostało usunięte w wersji 0.0.6 (EOL 2025-10-31). Wszystkie wersje są testowane w CI z 718 testami przy 100% pokryciu gałęzi.

Jakie są zależności?

Biblioteka podstawowa ma 5 bezpośrednich zależności:

• lxml -- Parsowanie XML ze wzmocnieniem zabezpieczeń
• pandas -- DataFrames i manipulacja danymi
• openpyxl -- Eksport do Excela
• pydantic -- Walidacja danych i modele
• defusedxml -- Ochrona XXE

Opcjonalne rozszerzenia dodają: litellm, pypdf, pdfplumber, pypdfium2, fastapi, uvicorn, polars.

Wszystkie zależności mają wersje zablokowane hashem SHA-256. CycloneDX SBOM mapuje każdy komponent środowiska wykonawczego.

Czy działa na macOS, Linux i Windows?

Tak. Biblioteka działa na macOS, Linux i Windows (przez WSL). Nie ma zależności specyficznych dla platformy.

Czy jest dostępne REST API?

Tak (od wersji 0.0.8+). Zainstaluj za pomocą pip install 'bankstatementparser[api]' i uruchom:

bankstatementparser-api --port 8000

Endpointy: POST /ingest (parsowanie wyciągu) i GET /health (sprawdzenie stanu).

Powtarzalność i bezpieczeństwo

Jak mogę zweryfikować powtarzalność?

python -m pytest                              # 718 tests, 100% branch coverage
python scripts/verify_locked_hashes.py        # SHA-256 hash verification
git log --show-signature -1                   # Verify commit signature

Jakie zabezpieczenia są wbudowane?

• Ochrona XXE: resolve_entities=False, no_network=True, load_dtd=False
• Ochrona przed ZIP bomb: Limity współczynnika kompresji, ograniczenia rozmiaru wpisów, odrzucanie wpisów zaszyfrowanych
• Zapobieganie przechodzeniu ścieżek: Lista blokowanych niebezpiecznych wzorców i rozpoznawanie dowiązań symbolicznych
• Walidacja danych wejściowych: Limity rozmiaru pliku (domyślnie 100 MB), walidacja rozszerzenia/formatu
• Łańcuch dostaw: Zależności zablokowane hashem SHA-256, CycloneDX SBOM, poświadczenie pochodzenia kompilacji
• Podpisane commity: Wymuszone w CI
• Lokalne LLM: Hybrydowy pipeline PDF używa Ollama — bez wywołań chmurowych API

Jak Bank Statement Parser wypada w porównaniu z pyiso20022?

pyiso20022 to szeroki zestaw narzędzi ISO 20022, który generuje klasy danych Pythona na podstawie schematów ISO XML. Obejmuje szeroką gamę typów komunikatów ISO 20022 (PACS, PAIN, CAMT, ADMI) z walidacją schematu. Bank Statement Parser jest stworzony specjalnie do parsowania wyciągów bankowych z hybrydową obsługą PDF, weryfikacją salda, wzbogacaniem, eksportem do księgi i ujednoliconym API dla siedmiu formatów, w tym formatów innych niż ISO (CSV, OFX, QFX, MT940, PDF). Jeśli potrzebujesz parsować wyciągi bankowe do DataFrames z zabezpieczeniami na poziomie produkcyjnym, użyj Bank Statement Parser. Jeśli potrzebujesz pełnego katalogu komunikatów ISO 20022, użyj pyiso20022.

Jakie są terminy migracji SWIFT ISO 20022?

SWIFT opublikował harmonogram etapowej migracji:

• Listopad 2026: Adresy strukturalne i hybrydowe stają się obowiązkowe. Komunikaty MT101 z wieloma instrukcjami zostaną odrzucone. Rozpoczyna się faza 1 zarządzania przypadkami.
• Listopad 2027: Wszystkie instytucje finansowe muszą mieć możliwość natywnego odbierania wyciągów CAMT.053. SWIFT przestanie konwertować MT do formatu ISO.
• Listopad 2028: Całkowite wycofanie MT940, MT942, MT950, MT900 i MT910. Zostaną one zastąpione odpowiednikami CAMT.052, CAMT.053 i CAMT.054.

Bank Statement Parser obsługuje zarówno starszy format MT940, jak i nowoczesne formaty CAMT.053/PAIN.001, dzięki czemu idealnie nadaje się na okres przejściowy.