Extração de comprovantes bancários brasileiros com IA

#ai #python #automation

Extrator de PIX/TED/DOC com Visão IA em Python

Recentemente me deparei com um problema em uma aplicação cuja interface de pagamento exige que o cliente preencha vários campos com dados extraídos do comprovante bancário. Isso vinha causando desistências, reclamações e preenchimentos incorretos. O motivo principal é que os comprovantes bancários têm layouts muito diversos entre os bancos, o que dificulta a identificação correta dos campos. Além disso, algumas pessoas têm dificuldade com tecnologia, e tudo o que pudermos fazer para facilitar essa interação é bem-vindo — não podemos abrir mão disso. Automatizar o processo, portanto, se tornou uma necessidade. O desafio era claro: o sistema precisava identificar e extrair dados de comprovantes automaticamente, sem depender das ferramentas tradicionais de OCR, que muitas vezes falham em interpretar os layouts dos bancos brasileiros.

Visão Computacional sem Templates e OCR Tradicional

Optamos por usar visão computacional alimentada por LLMs em vez das abordagens tradicionais de OCR. Esses modelos compreendem melhor as nuances dos layouts específicos de cada banco e eliminam a necessidade de templates configuráveis.

Desenvolvemos uma solução robusta com poucas linhas de código, mantendo a stack livre de frameworks pesados. Cada escolha foi deliberada:

Agno: optamos por ele devido ao suporte nativo ao Groq, o que o tornava mais leve em comparação ao LangChain.
Groq (Qwen 3.6-27B): preferimos o Groq por oferecer inferência rápida e barata.
pdf2image: a licença MIT foi um fator decisivo, evitando riscos legais associados a bibliotecas com licenciamento mais restritivo.
Pillow: escolhida por ser uma dependência leve.
Pydantic v2 e Hatchling: o primeiro garantiu validação robusta dos dados; o segundo cuidou do empacotamento e da publicação — tudo isso sem adicionar dependências desnecessárias.

Pipeline Modular e Segurança em Primeiro Lugar

Antes de qualquer processamento, os arquivos passam por uma validação rigorosa, que inclui a verificação por magic bytes — uma técnica essencial para prevenir ataques de spoofing. Quando um usuário envia um arquivo, o servidor lê apenas os primeiros bytes para checar se a assinatura corresponde ao tipo esperado. Por exemplo, se o usuário envia um arquivo .pdf, o sistema verifica os primeiros bytes para confirmar que se trata realmente de um PDF; caso contrário, o arquivo é rejeitado.

Além disso, práticas como o uso explícito de del para limpar dados da memória e o tratamento cuidadoso de exceções reforçam nosso compromisso com a segurança.

Cobertura de Testes Completa e Offline

Uma aplicação robusta, por menor que seja, exige uma boa cobertura de testes. Todos os testes foram desenvolvidos para rodar offline, graças ao mock dos agentes Groq, garantindo que o sistema funcione sob condições variadas — desde os diferentes padrões de formatação dos bancos brasileiros até a manipulação de PDFs corrompidos e imagens complexas.

Prompt Engineering em Português

A engenharia de prompts foi adaptada ao idioma português e ao domínio dos comprovantes bancários brasileiros, permitindo ao modelo compreender com maior precisão a estrutura e a semântica desses documentos. A incorporação de terminologia específica do contexto financeiro reduziu a ambiguidade na interpretação, diminuindo significativamente o risco de alucinações do modelo.

Três Dias para um Produto Completo

Este projeto foi feito com calma, em horários livres. Levei três dias, do conceito à publicação no PyPI. O alinhamento com SDD (Spec Driven Development) eliminou retrabalhos, e a publicação com Hatchling garantiu uma distribuição eficiente e sem complicações.

Alguns aprendizados desta implementação podem guiar futuros projetos:

SDD é eficaz: minimiza retrabalho e melhora o foco no essencial.
Testes com mocks são vitais: permitem validar o comportamento do LLM sem custos adicionais de API.
Segurança é para todos: implementações simples de segurança já proporcionam uma base robusta.
Adapte a linguagem ao domínio: criar prompts no mesmo idioma dos documentos analisados melhora significativamente a precisão do LLM.

A solução proposta não apenas resolve o problema de fricção no preenchimento de formulários, como também ilustra como uma abordagem bem planejada e executada pode levar a resultados relevantes. A automatização de formulários pode ser, ao mesmo tempo, eficiente, segura e capaz de melhorar a experiência do usuário.

Quer conhecer esse projeto?
git clone https://github.com/anomalyco/receipt-extractor
cd receipt-extractor
pip install -e .

Ou instale direto do PyPI:

pip install bank-receipt-extractor

from bank_receipt_extractor import extract_receipt

resultado = extract_receipt("meu_comprovante.pdf")
# → {'valor': 1500.00, 'tipo': 'PIX', 'favorecido': 'João Silva', ...}