🤖 DocPilot — Automação Inteligente de Documentos (RPA + IA)

RPA em Python que lê documentos, extrai dados com IA (LLM), valida regras de negócio e devolve tudo estruturado. Pensado como base para robôs de contas a pagar, onboarding de clientes e conferência fiscal.

RPA · Python · Inteligência Artificial · LLM · Automação de Processos · Extração de Dados · Document Processing · FastAPI · Pydantic · SQLite

---

💡 O problema

Times financeiros e de operações gastam horas relendo notas fiscais, faturas e boletos para lançar pagamentos. É trabalho repetitivo, sujeito a erro e que trava quando o documento vem em PDF, foto ou digitalizado.

O RPA tradicional (baseado em posição fixa de campo / template) quebra quando o layout muda. O DocPilot usa um LLM para entender o documento — funciona mesmo com layouts diferentes, sem template.

✨ O que ele faz

1. Lê o documento — PDF, imagem (foto/scan) ou texto.
2. Extrai os campos com IA em saída estruturada e validada (fornecedor, CNPJ, número, datas, valor, itens).
3. Valida regras de negócio (campos obrigatórios, vencimento coerente, soma dos itens x total, documento vencido…).
4. Classifica cada documento em ok / revisar / erro e persiste em banco.
5. Expõe tudo por CLI e por uma API HTTP (webhook) pronta para plugar em Bitrix24, filas, e-mail, etc.

🏗️ Arquitetura

                 ┌──────────────┐
  PDF / imagem   │   extract    │  Claude (messages.parse) → saída estruturada
  / texto  ───▶  │  (IA / demo) │  ou modo DEMO (regex, sem custo)
                 └──────┬───────┘
                        ▼
                 ┌──────────────┐
                 │   validate   │  regras de negócio → issues + status
                 └──────┬───────┘
                        ▼
                 ┌──────────────┐        ┌───────────┐
                 │    store     │ ─────▶ │  SQLite   │
                 └──────┬───────┘        └───────────┘
                        ▼
              CLI  ◀────┴────▶  API (FastAPI /process, /summary)

Cada etapa é um módulo isolado e testável (extract, validate, store, pipeline).

🚀 Começando

git clone https://github.com/matheusraull99/docpilot.git
cd docpilot
pip install -r requirements.txt

Modo DEMO (roda sem chave, sem custo)

O projeto vem com documentos de exemplo e um extrator simulado — dá pra ver tudo funcionando sem API key:

python -m docpilot.cli samples/

[OK]    nota_01.txt  (motor: demo)
  Fornecedor : Alpha Tecnologia LTDA  (12.345.678/0001-90)
  Documento  : 4501
  Total      : BRL 1500.0
[REVER] nota_02.txt  (motor: demo)
    ~ [warning] due_date: Documento já está vencido.
    ~ [warning] line_items: Soma dos itens (R$ 610.00) diverge do total (R$ 700.00).
[ERRO]  nota_03.txt  (motor: demo)
    ! [error] due_date: Vencimento anterior à data de emissão.

Resumo: 3 documento(s) | 1 com erro | 1 para revisar | 1 ok

Modo IA (documentos reais)

cp .env.example .env
# edite .env e coloque sua ANTHROPIC_API_KEY
python -m docpilot.cli caminho/para/notas/   # PDFs, imagens ou textos reais

Como API (webhook)

uvicorn docpilot.api:app --reload
# em outro terminal:
curl -F "file=@samples/nota_01.txt" http://localhost:8000/process

🧪 Testes

pytest -q      # 8 testes, sem rede e sem API

🧰 Stack

Camada	Tecnologia
Linguagem	Python 3.10+
IA / LLM	Claude (Anthropic) via SDK oficial, saída estruturada
Validação de dados	Pydantic v2
API	FastAPI + Uvicorn
Persistência	SQLite (portável para Postgres)
Testes	pytest

🗺️ Roadmap

• OCR local como fallback para digitalizações ruins
• Ingestão direta de e-mail (IMAP) e de pastas monitoradas
• Exportação para Excel / Google Sheets
• Dashboard de acompanhamento
• Suporte a mais tipos de documento (contratos, comprovantes)

📄 Licença

MIT — veja LICENSE.

---

Feito por Matheus Raul · automação de processos com Python e IA.