שאלות נפוצות

פרטיות נתונים וציות

האם נתונים כלשהם עוזבים את התשתית שלי?

לא — אפילו לא לחילוץ PDF. Bank Statement Parser פועל כספרייה חסרת מצב. כל העיבוד — ניתוח, עריכת PII, חילוץ ארכיונים — מתרחש בזיכרון הריצה המקומי שלך. ה-pipeline ההיברידי ל-PDF משתמש ב-Ollama להסקת LLM מקומית — ללא APIs בענן. מנתחי XML מוקשחים עם no_network=True, שחוסם כל גישה יוצאת ברמת המנתח. הנתונים הפיננסיים שלך לעולם לא עוזבים את הסביבה שלך.

איך עריכת PII ��ובדת?

שדות רגישים מוסתרים לפני שהם מגיעים ללוגיקת האפליקציה שלך. המנתח מזהה שמות חייבים, שמות זכאים, IBANs וכתובות דואר, ומחלי�� אותם ב-***REDACTED*** בפלט הקונסולה ובמצב streaming.

• עריכה פועלת כברירת מחדל בפלט CLI ובמצב streaming.
• ייצוא לקבצים (CSV, JSON, Excel) שומר נתונים מלאים לעיבוד במורד הזרם.
• הפעלה של נתונים מלאים עם --show-pii ב-CLI או redact_pii=False ב-API.

האם תהליך החילוץ דטרמיניסטי?

כן לפורמטים מובנים — פלט זהה בתים בכל הרצה. בהינתן אותו קובץ קלט, המנתחים הדטרמיניסטיים (CAMT, PAIN.001, CSV, OFX, QFX, MT940) מייצרים אותה תוצאה בכל פעם. ללא אקראיות, ללא הסקת מודל, ללא דגימה היוריסטית.

עבור ה-pipeline ההיברידי ל-PDF, נתיבי חילוץ מבוססי LLM עשויים לייצר שונויות קלות בין הרצות. לכן כל ח��לוץ PDF מאומת באמצעות כלל הזהב (opening + credits − debits == closing) ואי-התאמות שסומנו ניתנות לסקירה אינטראקטיבית.

CI אוכף דטרמיניזם עם 718 בדיקות בכיסוי branches של 100%, כולל fuzzing מבוסס מאפיינים דרך Hypothesis.

אילו תקני ציות הפרויקט עוקב אחריהם?

הפרויקט מתחזק תיעוד מיושר עם ISO 13485 עם עקיבות מלאה:

• רישום סיכונים מכומת עם דירוג חומרה/הסתברות והערכת סיכון שיורי.
• תוכנית אימות ו-Validation עם 19 שלבים מבוקרים על פני 5 שלבים.
• נוהל בקרת שינויים עם הערכת השפעה ופרוטוקולי חזרה.
• רישום SOUP המכסה את כל התלויות עם רמות סיכון ומעקב EOL.
• מטריצת עקיבות הממפה קלטי עיצוב למימוש ואימות.

כל גרסה כוללת CycloneDX SBOM, checksums SHA-256, ואישור מקור בנייה של GitHub.

ביצועים ומדרגיות

כמה מהיר Bank Statement Parser?

סף ביצועים מאומת ב-CI בכל commit:

מהירות חילוץ PDF תלויה בנתיב הניתוב: דטרמיניסטי (תת-שנייה), text-LLM (שניות), vision-LLM (שניות לדף).

איך קבצים גדולים מטופלים?

streaming עם זיכרון מוגבל — נבדק עם 50,000 עסקאות לקובץ. השתמש ב-parse_streaming() לעיבוד קבצי XML באופן מצטבר. כל עסקה מוחזרת כ-dictionary; אלמנטים מנוקים אחרי עיבוד למניעת צמיחת זיכרון. הז��כרון לא גדל עם גודל הקובץ — בדיקת 50K עסקאות (25+ MB) משתמשת בפחות מפי 2 מהזיכרון של בדיקת 10K עסקאות.

עבור קבצים מעל 50 MB (למשל, אצוות PAIN.001 host-to-host עם 100K+ תשלומים), המנתח עושה streaming דרך קובץ זמני עם הסרת namespaces לפי chunks — המסמך המלא לעולם לא נטען לזיכרון.

איך ארכיוני ZIP מעובדים בבטחה?

iter_secure_xml_entries() מאמת כל חבר לפני חילוץ:

• תקרת גודל ערך (ברירת מחדל 10 MB לערך)
• תקרת גודל מסה כולל (ברירת מחדל 50 MB)
• מגבלת יחס דחיסה (ברירת מחדל 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()

איך ה-pipeline ההיברידי ל-PDF עובד?

ה-pipeline ההיברידי (v0.0.5+) מנתב קבצי PDF בצורה חכמה דרך שלושה נתיבי חילוץ:

• נתיב A (דטרמיניסטי): טבלאות PDF מובנות מנותחות ישירות — חינם, המהיר ביותר, ללא צורך ב-LLM.
• נתיב B (Text-LLM): קבצי PDF דיגיטליים עם פריסות מורכבות נחלצים דרך LLM מקומי (LiteLLM/Ollama).
• נתיב C (Vision-LLM): דפי חשבון סרוקים או מצולמים מעובדים עם מודלים חזותיים רב-ממדיים.

כל חילוץ מאומת באמצעות כלל הזהב (opening + credits − debits == closing). אי-התאמות ניתנות לסקירה אינטראקטיבית עם --type review.

האם המנתח מטפל בדיאלקטים ספציפיים לבנקים של CAMT.053?

כן — אגנוסטי ל-namespaces מהעיצוב. המנ��ח מסיר namespaces של XML לפני עיבוד, ומטפל בכל וריאנט של CAMT.053 (camt.053.001.02, camt.053.001.04, או עטיפות קנייניות של בנקים) ללא הגדרה ספציפית ל-namespace. שאילתות XPath מכוונות למבנה אלמנטים, לא ל-URIs של namespace.

עבור בנקים שעוטפים CAMT במעטפת מותאמת, השתמש ב-from_string() או from_bytes() להזנת המסמך הפנימי ישירות.

האם ניתן למפות כותרות עמודות CSV מותאמות לסכמה הסטנדרטית?

כן — נרמול אוטומטי, אפס הגדרה. CsvStatementParser מזהה וריאציות נפוצות של כותרות: "Date", "Transaction Date", "Booking Date" כולם ממופים לשדה date. "Amount", "Value", "Sum" ממופים ל-amount. עמודות credit/debit מפוצלות (למשל, "Credit" ו-"Debit") מזוהות ומשולבות לסכום חתום אחד אוטומטית.

מה פורמט הפלט?

כל המנתחים מייצרים DataFrames סטנדרטיים של pandas עם סוגי עמודות עקביים:

פו��מט	עמודות מפתח
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, DataFrames של Polars, פורמט יומן hledger או beancount.

תכונות PDF ו-LLM

אילו מודלי LLM ה-pipeline ההיבריד�� תומך?

ה-pipeline משתמש ב-LiteLLM כשכבת הפשטה למודלים, עם גשר ישיר ל-Ollama עבור prompts חזותיים. מודלים מומלצים:

• חילוץ טקסט: כל מודל תואם LiteLLM (מקומי או מרוחק).
• חילוץ חזותי: ollama/minicpm-v (מומלץ) לקבצי PDF סרוקים.
• סיווג: כל מודל תואם LiteLLM.

כל המודלים יכולים לרוץ 100% מקומית דרך Ollama — ללא צורך ב-API keys.

מהו אימות כלל הזהב?

כל חי��וץ 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+). ייצוא עסקאות לפורמטים של חשבונאות בטקסט עם מיפוי חשבונות:

from bankstatementparser.export import to_hledger, to_beancount

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

תהליכי עבודה לאוצר

איך המנתח מטפל בדפי חשבון רב-מטבעיים?

כל עסקה שומרת על המטבע המקורי שלה — ללא המרה מרומזת. שדה Currency נחלץ מתכונת Ccy ב-XML לכל עסקה. דפי חשבון רב-מטבעיים נשארים כפי שהם. שיטת get_account_balances() מחזירה יתרות פתיחה וסגירה לכל חשבון עם קודי מטבע מקוריים.

מאז v0.0.8, verify_balance_multi_currency() מקבץ עסקאות לפי מטבע ומריץ את כלל הזהב באופן עצמאי לכל קבוצה — שימושי לחשבונות שמחזיקים מספר מטבעות.

האם המנתח תומך גם בפורמטים יוצאים וגם בנכנסים?

כן. Pain001Parser מטפל בקבצי ייזום העברת אשראי ISO 20022 PAIN.001 (תשלומים יוצאים). CamtParser מטפל בקבצי דף חשבון CAMT.053 מבנק ללקוח (דיווח נכנס). שניהם תומכים ב-streaming, עריכת PII וייצוא ל-CSV, JSON, Excel, hledger ו-beancount. השתמש ב-detect_statement_format() לזיהוי הפורמט אוטומטית.

מה קורה כשרשומת עסקה פגומה?

ההתנהגות תלויה במצב הניתוח:

• parse() (מצב אצווה) -- ערכים פגומים שחסרים שדות נדרשים (Amount, Currency, או CdtDbtInd) מדולגים עם אזהרה ביומן. שאר דף החשבון מנותח כרגיל.
• parse_streaming() (מצב streaming) -- שגיאות ניתוח מופצות מיד כחריגות. ללא אובדן נתונים שקט. התנהגות fail-fast זו מכוונת לתהליכי עבודה פיננסיים שבהם כל עסקה חייבת להיות מתועדת.
• smart_ingest() (PDF היברידי) -- שגיאות חילוץ נלכדות ב-IngestResult עם סטטוס אימות, מה שמאפשר סקירה אינטראקטיבית.

איך מניעת כפילויות עובדת?

לכל עסקה מוקצה transaction_hash אידמפוטנטי (טביעת אצבע MD5) על בסיס שדות המפתח שלה. זה מאפשר קליטה מצטברת בטוחה — עיבוד חוזר של אותו קובץ מייצר אותם hashes, כך שכפילויות מזוהות אוטומטית.

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 בדיקות בכיסוי branches של 100%.

מהן התלויות?

לספריית הליבה 5 תלויות ישירות:

• lxml -- ניתוח XML עם הקשחת אבטחה
• pandas -- DataFrames ומניפולציית נתונים
• openpyxl -- ייצ��א Excel
• pydantic -- אימות נתונים ומודלים
• defusedxml -- הגנת XXE

תוספות אופציונליות מוסיפות: litellm, pypdf, pdfplumber, pypdfium2, fastapi, uvicorn, polars.

לכל התלויות גרסאות נעולות ב-SHA-256 hash. ה-CycloneDX SBOM ממפה כל רכיב runtime.

האם עובד על macOS, Linux ו-Windows?

כן. הספרייה עובדת על macOS, Linux ו-Windows (דרך WSL). אין לה תלויות ספציפיות לפלטפורמה.

האם יש REST API?

כן (v0.0.8+). התקן עם pip install 'bankstatementparser[api]' והרץ:

bankstatementparser-api --port 8000

Endpoints: 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: מגבלות יחס דחיסה, תקרות גודל ערך, דחיית ערכים מוצפנים
• מניעת חציית נתיבים: רשימת חסימות של דפוסים מסוכנים ורזולוציית symlinks
• אימות קלט: מגבלות גודל קובץ (ברירת מחדל 100 MB), אימות סיומות/פורמט
• שרשרת אספקה: תלויות נעולות ב-SHA-256 hash, CycloneDX SBOM, אישור מקור בנייה
• commits חתומים: נאכף ב-CI
• LLMs מקומיים: Pipeline היברידי ל-PDF משתמש ב-Ollama — ללא קריאות API לענן

איך Bank Statement Parser משתווה ל-pyiso20022?

pyiso20022 היא ערכת כלים רחבה ל-ISO 20022 שמייצרת dataclasses של Python מסכמות XML של ISO. היא מכסה מגוון רחב של סוגי הודעות ISO 20022 (PACS, PAIN, CAMT, ADMI) עם אימות סכמה. Bank Statement Parser בנוי ייעודית לניתוח דפי חשבון בנק עם תמיכה היברידית ב-PDF, אימות יתרה, העשרה, ייצוא ל-ledger, ו-API מאוחד על פני שבעה פורמטים כולל פורמטים שאינם ISO (CSV, OFX, QFX, MT940, PDF). אם אתה צריך לנתח דפי חשבון בנק לתוך DataFrames עם אבטחה ברמת ייצור, השתמש ב-Bank Statement Parser. אם אתה צריך לעבוד עם קטלוג ההודעות המלא של ISO 20022, השתמש ב-pyiso20022.

מהם מועדי הגירת SWIFT ISO 20022?

SWIFT פרסמה ציר זמן הגירה מדורג:

• נובמבר 2026: כתובות מובנות והיברידיות הופכות לחובה. הודעות MT101 רב-הוראתיות יידחו. שלב 1 של ניהול מקרים מתחיל.
• נובמבר 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, מה שהופך אותו לאידיאלי לתקופת המעבר.