শুরু করা

প্রয়োজনীয়তা

• Python 3.10 থেকে 3.14
• টার্মিনাল অ্যাক্সেস (macOS, Linux, বা WSL)

ইনস্টল করুন

# Core install (deterministic parsers only)
pip install bankstatementparser

অতিরিক্ত ক্ষমতার জন্য ঐচ্ছিক extras:

# Text-LLM path for digital PDFs (litellm + pypdf)
pip install 'bankstatementparser[hybrid]'

# Higher-fidelity table extraction (adds pdfplumber)
pip install 'bankstatementparser[hybrid-plus]'

# Vision-LLM path for scanned PDFs (adds pypdfium2)
pip install 'bankstatementparser[hybrid-vision]'

# LLM-powered transaction categorisation
pip install 'bankstatementparser[enrichment]'

# REST API microservice (FastAPI + uvicorn)
pip install 'bankstatementparser[api]'

# Optional Polars DataFrame support
pip install 'bankstatementparser[polars]'

দ্রুত শুরু

অটো-ডিটেক্ট এবং যেকোনো স্ট্রাকচার্ড ফর্ম্যাট পার্স করুন

from bankstatementparser import create_parser, detect_statement_format

fmt = detect_statement_format("transactions.ofx")
parser = create_parser("transactions.ofx", fmt)
df = parser.parse()  # pandas DataFrame
print(df.head())

এটি .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940, এবং .sta ফাইলের সাথে কাজ করে।

CAMT.053 পার্স করুন

from bankstatementparser import CamtParser

parser = CamtParser("statement.xml")
transactions = parser.parse()

PAIN.001 পার্স করুন

from bankstatementparser import Pain001Parser

parser = Pain001Parser("payment.xml")
payments = parser.parse()

PDF ব্যাঙ্ক স্টেটমেন্ট পার্স করুন (Hybrid Pipeline)

Hybrid pipeline বুদ্ধিমত্তার সাথে PDF তিনটি extraction পথে রাউট করে:

from bankstatementparser.hybrid import smart_ingest

result = smart_ingest("statement.pdf")
print(result.source_method)         # "deterministic" | "llm" | "vision"
print(result.verification.status)   # VERIFIED | DISCREPANCY | FAILED
print(result.transactions)          # List of extracted transactions

প্রতিটি extraction Golden Rule দিয়ে যাচাই করা হয়: opening + credits − debits == closing।

বড় ফাইল Streaming

হাজার হাজার লেনদেন সহ ফাইলের জন্য, মেমরি সীমাবদ্ধ রাখতে streaming ব্যবহার করুন:

parser = CamtParser("large_statement.xml")
for transaction in parser.parse_streaming(redact_pii=True):
    process(transaction)  # Memory stays constant

In-Memory পার্সিং

ডিস্ক I/O ছাড়া বাইট থেকে পার্স করুন -- SFTP বা API ওয়ার্কফ্লোর জন্য উপযোগী:

xml_bytes = download_from_sftp()
parser = CamtParser.from_bytes(xml_bytes, source_name="daily.xml")
transactions = parser.parse()

Parallel ফাইল Processing

একসাথে একাধিক ফাইল পার্স করুন:

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

Bulk Directory Scanning

স্বয়ংক্রিয় ডিডুপ্লিকেশন সহ সম্পূর্ণ ফোল্ডার ট্রি প্রক্রিয়া করুন:

from bankstatementparser.hybrid import scan_and_ingest

batch = scan_and_ingest("statements/2026/", pattern="**/*.pdf")
print(f"Processed: {len(batch.results)} files")
print(f"Unique transactions: {batch.unique_count}")

Deduplication

নিরাপদ ইনক্রিমেন্টাল ইনজেশনের জন্য idempotent transaction 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)}")

Transaction Categorisation (Enrichment)

LLM-চালিত ক্লাসিফিকেশন ব্যবহার করে স্বয়ংক্রিয়ভাবে লেনদেন ক্যাটাগরাইজ করুন:

from bankstatementparser.enrichment import Categorizer

categorizer = Categorizer()
enriched = categorizer.categorize_batch(transactions)
for txn in enriched:
    print(f"{txn.description}: {txn.category}")

Ledger Export (hledger / beancount)

Plaintext-accounting জার্নাল ফর্ম্যাটে লেনদেন এক্সপোর্ট করুন:

from bankstatementparser.export import to_hledger, to_beancount

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

Multi-Currency Balance Verification

প্রতিটি মুদ্রা গোষ্ঠীর জন্য স্বতন্ত্রভাবে ব্যালেন্স যাচাই করুন:

from bankstatementparser.hybrid import verify_balance_multi_currency

results = verify_balance_multi_currency(transactions)
for currency, verification in results.items():
    print(f"{currency}: {verification.status}")

REST API

FastAPI মাইক্রোসার্ভিস হিসেবে ডিপ্লয় করুন:

# Start the API server
bankstatementparser-api --port 8000

# For container deployments
bankstatementparser-api --host 0.0.0.0 --port 9000

Endpoints:

• POST /ingest -- একটি ব্যাঙ্ক স্টেটমেন্ট ফাইল পার্স করুন
• GET /health -- Health check

Secure ZIP Processing

বিল্ট-ইন নিরাপত্তা চেক (বোমা সুরক্ষা, এনক্রিপ্টেড এন্ট্রি প্রত্যাখ্যান) সহ জিপ করা XML ফাইল প্রক্রিয়া করুন:

from bankstatementparser import iter_secure_xml_entries, CamtParser

for entry in iter_secure_xml_entries("statements.zip"):
    parser = CamtParser.from_bytes(entry.xml_bytes, source_name=entry.source_name)
    print(f"{entry.source_name}: {len(parser.parse())} transactions")

Export

parser = CamtParser("statement.xml")
parser.export_csv("output.csv")
parser.export_json("output.json")

# Polars (requires bankstatementparser[polars])
polars_df = parser.to_polars()

# Excel
parser.camt_to_excel("output.xlsx")

CLI ব্যবহার

# Parse structured formats
bankstatementparser --type camt --input statement.xml
bankstatementparser --type pain001 --input payment.xml

# Hybrid PDF pipeline
bankstatementparser --type ingest --input statement.pdf
bankstatementparser --type ingest --input statement.pdf --output ledger.csv

# Interactive review mode
bankstatementparser --type review --input result.json
bankstatementparser --type review --input result.json --output reviewed.json

# Export to CSV with streaming
bankstatementparser --type camt --input statement.xml --output transactions.csv
bankstatementparser --type camt --input statement.xml --streaming --show-pii

CLI অপশন:

• --type {camt,pain001,ingest,review} -- পার্সার টাইপ বা মোড
• --input <path> -- ইনপুট ফাইল
• --output <path> -- এক্সপোর্ট ফাইল (CSV বা JSON)
• --streaming -- বড় ফাইল stream করুন
• --show-pii -- সংবেদনশীল ক্ষেত্র দেখান (ডিফল্টরূপে রিডাক্ট করা)
• --max-size <MB> -- ফাইল সাইজ সীমা

স্থানীয় ডেভেলপমেন্ট সেটআপ

git clone https://github.com/sebastienrousseau/bankstatementparser.git
cd bankstatementparser
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

টেস্ট স্যুট চালান:

pytest

API রেফারেন্স

পার্সার ক্লাস

ইউটিলিটি ফাংশন

ফাংশন	উদ্দেশ্য
detect_statement_format(path)	ফাইল ফর্ম্যাট অটো-ডিটেক্ট করুন
create_parser(path, fmt)	উপযুক্ত পার্সার তৈরি করুন
parse_files_parallel(paths)	একসাথে একাধিক ফাইল পার্স করুন
iter_secure_xml_entries(zip_path)	নিরাপদে ZIP এন্ট্রি iterate করুন
smart_ingest(path)	যাচাই সহ hybrid PDF extraction
scan_and_ingest(dir, pattern)	Bulk directory scanning
verify_balance_multi_currency(txns)	প্রতি-মুদ্রা ব্যালেন্স যাচাই
to_hledger(txns, account)	hledger জার্নাল ফর্ম্যাটে এক্সপোর্ট
to_beancount(txns, account)	beancount জার্নাল ফর্ম্যাটে এক্সপোর্ট

ডেটা ক্লাস

ক্লাস	উদ্দেশ্য
Deduplicator	ডুপ্লিকেট লেনদেন শনাক্ত করুন
DeduplicationResult	ইউনিক, exact, ও suspected match এর ফলাফল
InputValidator	ফাইল পাথ ও ফর্ম্যাট ভ্যালিডেট করুন
Transaction	নরমালাইজড লেনদেনের রেকর্ড
FileResult	Parallel parsing থেকে ফলাফল
ZipXMLSource	ZIP member wrapper
IngestResult	যাচাই সহ hybrid pipeline ফলাফল
VerificationResult	ব্যালেন্স যাচাইয়ের ফলাফল
Categorizer	LLM-চালিত transaction categorisation
AccountMapper	Regex-ভিত্তিক account mapping নিয়ম

Exceptions

Exception	কখন উত্থাপিত হয়
ParserError	পার্সিং ব্যর্থতা
ExportError	এক্সপোর্ট ব্যর্থতা (CSV/JSON/Excel)
ValidationError	ইনপুট ভ্যালিডেশন ব্যর্থতা
ZipSecurityError	ZIP নিরাপত্তা চেক ব্যর্থতা