FAQ

Конфіденційність даних і комплаєнс

Чи залишають дані мою інфраструктуру?

Ні — навіть для витягування з PDF. Bank Statement Parser працює як бібліотека без збереження стану. Уся обробка — аналіз, приховування персональних даних, витягування з архівів — відбувається у вашій локальній пам'яті. Гібридний PDF pipeline використовує Ollama для локального LLM-виведення — без хмарних API. XML-парсери захищені параметром no_network=True, що блокує весь вихідний доступ на рівні парсера. Ваші фінансові дані ніколи не залишають ваше середовище.

Як працює приховування персональних даних?

Конфіденційні поля маскуються до того, як вони потраплять у логіку вашого застосунку. Парсер виявляє імена боржників, імена кредиторів, IBAN та поштові адреси, замінюючи їх на ***REDACTED*** у консольному виводі та streaming-режимі.

• Приховування увімкнене за замовчуванням у CLI та streaming-режимі.
• Експорт файлів (CSV, JSON, Excel) зберігає повні дані для подальшої обробки.
• Увімкніть відображення повних даних через --show-pii у CLI або redact_pii=False в API.

Чи є процес витягування детерміністичним?

Так для структурованих форматів — побайтово ідентичний результат щоразу. За умови однакового вхідного файлу детерміністичні парсери (CAMT, PAIN.001, CSV, OFX, QFX, MT940) щоразу дають однаковий результат. Без випадковості, без моделювання, без евристичної вибірки.

Для гібридного PDF pipeline шляхи витягування на основі LLM можуть давати незначні відмінності між запусками. Саме тому кожне PDF-витягування перевіряється Золотим правилом (opening + credits − debits == closing), а виявлені розбіжності можна переглянути інтерактивно.

CI забезпечує детермінізм за допомогою 718 тестів зі 100% покриттям гілок, включно з property-based фаззингом через Hypothesis.

Яким стандартам комплаєнсу відповідає проект?

Проект підтримує документацію, узгоджену з ISO 13485, із повною відстежуваністю:

• Кількісний Реєстр ризиків з оцінкою серйозності/ймовірності та оцінкою залишкового ризику.
• План верифікації та валідації з 19 контрольними кроками через 5 фаз.
• Процедура контролю змін з оцінкою впливу та протоколами відкату.
• Реєстр SOUP, що охоплює всі залежності з рівнями ризику та відстеженням EOL.
• Матриця відстежуваності, що зв'язує вхідні дані проєктування з реалізацією та верифікацією.

Кожний реліз містить CycloneDX SBOM, контрольні суми SHA-256 та атестацію походження збірки GitHub.

Продуктивність і масштабованість

Як швидко працює Bank Statement Parser?

Порогові значення продуктивності перевіряються в CI під час кожного коміту:

Швидкість витягування з PDF залежить від шляху маршрутизації: детерміністичний (менше секунди), текстовий LLM (секунди), vision LLM (секунди на сторінку).

Як обробляються великі файли?

Streaming з обмеженою пам'яттю — протестовано на 50 000 транзакцій на файл. Використовуйте parse_streaming() для поступової обробки XML-файлів. Кожна транзакція видається як словник; елементи очищуються після обробки для запобігання зростанню пам'яті. Пам'ять не зростає з розміром файлу — тест на 50K транзакцій (25+ МБ) використовує менше ніж у 2 рази більше пам'яті, ніж тест на 10K транзакцій.

Для файлів понад 50 МБ (наприклад, пакети PAIN.001 з 100K+ платежів) парсер передає дані через тимчасовий файл із порційним видаленням просторів імен — повний документ ніколи не завантажується в пам'ять.

Як безпечно обробляються ZIP-архіви?

iter_secure_xml_entries() перевіряє кожний запис перед витягуванням:

• Ліміт розміру запису (за замовчуванням 10 МБ на запис)
• Ліміт загального нестиснутого розміру (за замовчуванням 50 МБ)
• Обмеження коефіцієнта стиснення (за замовчуванням 100:1) для захисту від ZIP-бомб
• Відхилення зашифрованих записів

Жодний файл не записується на диск. XML-байти передаються напряму до парсера через from_bytes().

Чи можу я аналізувати кілька файлів паралельно?

Так. Використовуйте parse_files_parallel(), який розподіляє роботу через 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")

Для масового завантаження PDF використовуйте scan_and_ingest(), який обробляє цілі дерева каталогів з автоматичною дедуплікацією.

Підтримувані формати

Які формати банківських виписок підтримуються?

Формат	Стандарт	Типи файлів	Парсер/Метод
CAMT.053	ISO 20022 Виписка банку для клієнта	.xml	CamtParser
PAIN.001	ISO 20022 Ініціювання кредитового переказу	.xml	Pain001Parser
CSV	Загальний банківський експорт	.csv	CsvStatementParser
OFX	Open Financial Exchange	.ofx	OfxParser
QFX	Quicken Financial Exchange	.qfx	QfxParser
MT940	Стандарт SWIFT	.mt940, .sta	Mt940Parser
PDF	Цифрові та скановані виписки	.pdf	smart_ingest()

Як працює гібридний PDF pipeline?

Гібридний pipeline (v0.0.5+) інтелектуально маршрутизує PDF через три шляхи витягування:

• Шлях A (Детерміністичний): Структуровані PDF-таблиці аналізуються напряму — безкоштовно, найшвидше, без LLM.
• Шлях B (Текстовий LLM): Цифрові PDF зі складною структурою обробляються локальним LLM (LiteLLM/Ollama).
• Шлях C (Vision LLM): Скановані або фотокопійовані виписки обробляються мультимодальними моделями.

Кожне витягування перевіряється Золотим правилом (opening + credits − debits == closing). Розбіжності можна переглянути інтерактивно через --type review.

Чи обробляє парсер банківські діалекти CAMT.053?

Так — не залежить від просторів імен за дизайном. Парсер видаляє простори імен XML перед обробкою, працюючи з будь-яким варіантом CAMT.053 (camt.053.001.02, camt.053.001.04 або пропрієтарними банківськими обгортками) без конфігурації просторів імен. XPath-запити спрямовані на структуру елементів, а не на URI просторів імен.

Для банків, що загортають CAMT у власний конверт, використовуйте from_string() або from_bytes() для подачі внутрішнього документа напряму.

Чи можу я зіставити власні заголовки стовпців CSV зі стандартною схемою?

Так — автоматична нормалізація, нульова конфігурація. CsvStatementParser розпізнає типові варіанти заголовків: "Date", "Transaction Date", "Booking Date" — усі зіставляються з полем date. "Amount", "Value", "Sum" зіставляються з amount. Розділені стовпці кредиту/дебету (наприклад, "Credit" і "Debit") автоматично виявляються та об'єднуються в одну суму зі знаком.

Який вихідний формат?

Усі парсери створюють стандартизовані pandas DataFrames з однаковими типами стовпців:

Формат	Ключові стовпці
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 (нормалізовані)

Ви також можете експортувати у CSV, JSON, Excel, Polars DataFrames, hledger або формат beancount.

PDF та LLM функції

Які LLM-моделі підтримує гібридний pipeline?

Pipeline використовує LiteLLM як шар абстракції моделей, із прямим мостом до Ollama для vision-промптів. Рекомендовані моделі:

• Витягування тексту: Будь-яка модель, сумісна з LiteLLM (локальна або віддалена).
• Vision-витягування: ollama/minicpm-v (рекомендовано) для сканованих PDF.
• Категоризація: Будь-яка модель, сумісна з LiteLLM.

Усі моделі можуть працювати 100% локально через Ollama — API-ключі не потрібні.

Що таке перевірка Золотим правилом?

Кожне PDF-витягування перевіряється рівнянням: opening balance + credits − debits == closing balance. Результати позначаються як:

• VERIFIED: Баланси збігаються точно.
• DISCREPANCY: Баланси не збігаються — рекомендується перевірка.
• FAILED: Перевірку не вдалося виконати (відсутні дані балансу).

Чи можу я автоматично категоризувати транзакції?

Так. Модуль збагачення (v0.0.6+) надає категоризацію транзакцій за допомогою LLM:

from bankstatementparser.enrichment import Categorizer

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

Схема за замовчуванням використовує 13 Plaid-сумісних категорій. Ви можете надати власну схему категорій.

Чи можу я експортувати в hledger або beancount?

Так (v0.0.8+). Експорт транзакцій у формати plaintext-accounting з маппінгом рахунків:

from bankstatementparser.export import to_hledger, to_beancount

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

Робочі процеси казначейства

Як парсер обробляє мультивалютні виписки?

Кожна транзакція зберігає свою оригінальну валюту — без прихованої конвертації. Поле Currency витягується з XML-атрибуту Ccy для кожної транзакції. Мультивалютні виписки залишаються без змін. Метод get_account_balances() повертає початкові та кінцеві залишки за рахунком з оригінальними кодами валют.

Починаючи з v0.0.8, verify_balance_multi_currency() групує транзакції за валютою та виконує Золоте правило незалежно для кожної групи — зручно для рахунків із кількома валютами.

Чи підтримує парсер як вихідні, так і вхідні формати?

Так. Pain001Parser обробляє файли ініціювання кредитових переказів ISO 20022 PAIN.001 (вихідні платежі). CamtParser обробляє файли виписок CAMT.053 від банку до клієнта (вхідні звіти). Обидва підтримують streaming, приховування персональних даних та експорт у CSV, JSON, Excel, hledger та beancount. Використовуйте detect_statement_format() для автоматичного визначення формату.

Що станеться, якщо запис транзакції має неправильний формат?

Поведінка залежить від режиму аналізу:

• parse() (пакетний режим) -- Помилкові записи без обов'язкових полів (Amount, Currency або CdtDbtInd) пропускаються з попередженням у журналі. Решта виписки аналізується нормально.
• parse_streaming() (streaming-режим) -- Помилки аналізу миттєво поширюються як винятки. Без тихої втрати даних. Така fail-fast поведінка навмисна для фінансових робочих процесів, де кожна транзакція має бути врахована.
• smart_ingest() (гібридний PDF) -- Помилки витягування фіксуються в IngestResult зі статусом перевірки, що дозволяє інтерактивний перегляд.

Як працює дедуплікація?

Кожній транзакції присвоюється ідемпотентний transaction_hash (MD5-відбиток) на основі її ключових полів. Це забезпечує безпечне інкрементальне завантаження — повторна обробка того самого файлу дає ті самі hash, тому дублікати виявляються автоматично.

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)}")

Встановлення та сумісність

Як встановити 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

Які версії Python підтримуються?

Python 3.10–3.14. Підтримку Python 3.9 було припинено у v0.0.6 (EOL 2025-10-31). Усі версії тестуються в CI з 718 тестами при 100% покритті гілок.

Які залежності?

Базова бібліотека має 5 прямих залежностей:

• lxml -- Аналіз XML із захистом безпеки
• pandas -- DataFrames та маніпулювання даними
• openpyxl -- Експорт в Excel
• pydantic -- Валідація даних та моделі
• defusedxml -- Захист від XXE

Додаткові модулі включають: litellm, pypdf, pdfplumber, pypdfium2, fastapi, uvicorn, polars.

Усі залежності мають версії із SHA-256 hash-блокуванням. CycloneDX SBOM описує кожний компонент.

Чи працює на macOS, Linux і Windows?

Так. Бібліотека працює на macOS, Linux та Windows (через WSL). Немає платформо-залежних залежностей.

Чи є REST API?

Так (v0.0.8+). Встановіть через pip install 'bankstatementparser[api]' та запустіть:

bankstatementparser-api --port 8000

Ендпоінти: POST /ingest (аналіз виписки) та GET /health (перевірка стану).

Відтворюваність і безпека

Як перевірити відтворюваність?

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

Які засоби захисту вбудовані?

• Захист від XXE: resolve_entities=False, no_network=True, load_dtd=False
• Захист від ZIP-бомб: Обмеження коефіцієнта стиснення, ліміти розміру записів, відхилення зашифрованих записів
• Захист від обходу шляхів: Блокування небезпечних шаблонів та розв'язання символічних посилань
• Валідація вхідних даних: Ліміти розміру файлів (100 МБ за замовчуванням), перевірка розширення/формату
• Ланцюг постачань: Залежності із SHA-256 hash-блокуванням, CycloneDX SBOM, атестація походження збірки
• Підписані коміти: Обов'язкові в CI
• Локальні LLM: Гібридний PDF pipeline використовує Ollama — без хмарних API-викликів

Як Bank Statement Parser порівнюється з pyiso20022?

pyiso20022 — це широкий набір інструментів ISO 20022, який генерує Python dataclasses зі схем ISO XML. Він охоплює широкий спектр типів повідомлень ISO 20022 (PACS, PAIN, CAMT, ADMI) з валідацією схем. Bank Statement Parser створений спеціально для аналізу банківських виписок із гібридною підтримкою PDF, перевіркою балансу, збагаченням, експортом у бухгалтерію та єдиним API для семи форматів, включно з не-ISO (CSV, OFX, QFX, MT940, PDF). Якщо вам потрібно аналізувати банківські виписки в DataFrames із продакшен-рівнем безпеки, використовуйте Bank Statement Parser. Якщо потрібно працювати з повним каталогом повідомлень ISO 20022, використовуйте pyiso20022.

Які дедлайни міграції SWIFT ISO 20022?

SWIFT опублікував графік поетапної міграції:

• Листопад 2026: Структуровані та гібридні адреси стають обов'язковими. Повідомлення MT101 з кількома інструкціями будуть відхилятися. Починається Фаза 1 Case Management.
• Листопад 2027: Усі фінансові установи мають мати можливість отримувати виписки CAMT.053 нативно. SWIFT припинить конвертацію MT у формат ISO.
• Листопад 2028: Повне припинення MT940, MT942, MT950, MT900 та MT910. Їх замінять еквіваленти CAMT.052, CAMT.053 та CAMT.054.

Bank Statement Parser підтримує як застарілий формат MT940, так і сучасні формати CAMT.053/PAIN.001, що робить його ідеальним для перехідного періоду.