Sobre o analisador de extrato bancário

TL;DR: Bank Statement Parser é uma biblioteca Python de código aberto que analisa sete formatos de extrato bancário (CAMT.053, PAIN.001, CSV, OFX, QFX, MT940 e PDF) em DataFrames pandas. Pipeline híbrido de PDF com verificação de saldo, REST API, enriquecimento, exportação contábil, mais de 27 mil tx/s.

Bank Statement Parser é uma biblioteca Python de código aberto que analisa extratos bancários de sete formatos em DataFrames pandas estruturados. O núcleo determinístico processa formatos estruturados localmente, sem chamadas de rede. O pipeline híbrido de PDF opcional usa LLMs locais (via Ollama) para extratos digitais e digitalizados.

Para Quem É?

• Equipes de tesouraria migrando de MT940 para CAMT.053 que precisam de um analisador que lide com formatos antigos e novos durante a transição, além de extratos em PDF de bancos que não oferecem exportações estruturadas.
• Desenvolvedores fintech criando pipelines de reconciliação, relatórios ou contabilidade que querem uma única dependência com verificação de saldo, categorização e exportação contábil integrados.
• Equipes de conformidade que precisam de redação de PII por padrão, saída determinística e verificação Golden Rule que sinaliza discrepâncias antes de chegarem ao livro-razão.
• Usuários de contabilidade em texto simples que querem ingestão automática de extratos bancários em PDF direto para journals hledger ou beancount.
• Qualquer pessoa que se recuse a enviar dados financeiros sensíveis para um SaaS de terceiros quando uma ferramenta local e de código aberto pode fazer o trabalho.

Formatos Suportados

Todos os formatos produzem DataFrames pandas normalizados com nomes de colunas consistentes, tornando o processamento posterior independente do formato.

Principais Recursos

• Pipeline Híbrido de PDF: smart_ingest() roteia PDFs por três caminhos — extração determinística de tabelas, text-LLM ou vision-LLM — com verificação automática de saldo pela Golden Rule.
• Detecção Automática de Formato: detect_statement_format() identifica o formato; create_parser() instancia o analisador correto.
• Verificação de Saldo: Verificação Golden Rule (opening + credits − debits == closing) com status VERIFIED/DISCREPANCY/FAILED.
• Verificação Multimoeda: verify_balance_multi_currency() agrupa transações por moeda para verificação independente.
• REST API: Microsserviço FastAPI com endpoints /ingest e /health para implantações em produção.
• Enriquecimento: Categorização de transações via LLM com schemas configuráveis (padrão Plaid de 13 categorias).
• Revisão Interativa: Navegue por discrepâncias com ações aceitar/editar/pular/excluir via --type review.
• Exportação Contábil: to_hledger() e to_beancount() para fluxos de trabalho de contabilidade em texto simples.
• Varredura em Massa: scan_and_ingest() processa árvores de pastas com deduplicação automática entre arquivos.
• Mapeamento de Contas: Regras de mapeamento de contas baseadas em regex a partir de configuração JSON para exportação contábil.
• Análise via Streaming: Processe arquivos grandes (50 MB+, 50K+ transações) com memória limitada usando parse_streaming().
• Processamento Paralelo: Analise vários arquivos simultaneamente com parse_files_parallel() usando ProcessPoolExecutor.
• Deduplicação: transaction_hash idempotente (fingerprint MD5) para ingestão incremental segura.
• Análise em Memória: from_string() e from_bytes() para fluxos de trabalho SFTP e API sem E/S de disco.
• Processamento ZIP Seguro: iter_secure_xml_entries() com limites de taxa de compressão, limites de tamanho de entrada e rejeição de entradas criptografadas.
• Exportação: CSV, JSON, Excel (.xlsx), DataFrames Polars, journals hledger e beancount.

Segurança e Privacidade

• Redação de PII: Nomes, IBANs e endereços são mascarados por padrão na saída CLI. Ative com --show-pii.
• Proteção XXE: A análise XML usa resolve_entities=False, no_network=True, load_dtd=False.
• Proteção contra ZIP Bomb: Limites de taxa de compressão (padrão 100:1), limites de tamanho de entrada (10 MB), rejeição de entradas criptografadas.
• Prevenção de Travessia de Caminho: Lista de bloqueio de padrões perigosos e resolução de links simbólicos.
• Segurança da Cadeia de Suprimentos: Dependências bloqueadas por hash SHA-256, CycloneDX SBOM, atestado de procedência de build.
• Apenas LLMs Locais: O pipeline híbrido de PDF usa Ollama para inferência local — nenhum dado é enviado para APIs na nuvem.

Desempenho

Métrica	Valor
Throughput CAMT.053	27.000+ tx/s
Throughput PAIN.001	52.000+ tx/s
Latência por transação (CAMT)	37 microssegundos
Latência por transação (PAIN.001)	19 microssegundos
Tempo para o primeiro resultado	< 2 ms
Escala de memória (1K-50K tx)	Constante (streaming)
Cobertura de testes	100% de cobertura de ramificação
Testes	718 em 29 arquivos de teste

Comece Agora

Comece com a instalação e exemplos ❯

"Repositório GitHub"