Cartorio OCR Pipeline

Projeto independente criado a partir da parte de leitura/OCR do Brass, preparado para testar um pipeline de transcricao de documentos antigos de cartorio fora do app principal.

Este repositório é uma base de colaboração para ajudar Roney e Pedro a desenvolverem, testarem e compararem abordagens modernas de OCR/HTR para livros antigos de cartório, com foco em transcrição auditável, estruturação em JSON e revisão humana nos casos duvidosos.

Estado em 20 de junho de 2026: base endurecida para API/CLI, validacao local e evolucao para pipeline multi-modelo. Ainda nao inclui pesos locais de GLM-OCR, MiniCPM, DeepSeek-OCR ou Kraken; esses entram como leitores adicionais depois de validar hardware, licenca, custo e acuracia em amostras reais.

Estrutura

• cartorio_ocr/app.py: aplicacao FastAPI com lifespan, validacao de upload, modelos de resposta e status codes.
• cartorio_ocr/config.py: configuracao tipada com Pydantic Settings e .env.
• cartorio_ocr/cli.py: OCR direto em arquivo local, sem subir API.
• cartorio_ocr/registry_schema.py: contrato JSON para nomes, datas, livro, folha, tipo de ato e evidencias.
• cartorio_ocr/evaluation.py: CER/WER para comparar leitores OCR/HTR em amostras corrigidas.
• services/gemini_ocr.py: nucleo OCR clonado do backend Cloud Run do Brass.
• standalone_ocr_api.py: entrypoint compatível para uvicorn.
• legacy-reference/: referencias antigas/experimentais do Brass.
• tests/: testes leves de contrato, configuracao, schema e metricas.

Origem: C:\Users\roney\WebstormProjects\Brass\ocr-reading-clone.

Fluxo atual

O caminho operacional atual e o GeminiOCR:

1. Recebe PDF, imagem ou DOCX.
2. Para PDF, renderiza cada pagina em imagem com PyMuPDF, por padrao em 300 DPI.
3. Normaliza a imagem com Pillow, autocontraste e redimensionamento minimo.
4. Envia cada pagina para Gemini com prompt estrito de transcricao.
5. Faz uma segunda passada quando o texto parece curto ou contem muitos marcadores de ilegivel.
6. Opcionalmente pede estrutura JSON da primeira pagina.

Isso e adequado como baseline. Para livros antigos de cartorio, nao deve ser o unico leitor.

Como rodar a API

cd C:\Users\roney\WebstormProjects\Cartorio-OCR-Pipeline
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
uvicorn standalone_ocr_api:app --host 0.0.0.0 --port 8081

Teste:

curl.exe http://localhost:8081/health
curl.exe -F "file=@C:\caminho\documento.pdf" http://localhost:8081/ocr

Como rodar por CLI

python -m cartorio_ocr.cli C:\caminho\documento.pdf --format json --output output\resultado.json
python -m cartorio_ocr.cli C:\caminho\documento.pdf --format text --output output\transcricao.txt

Validacao

python -B -m py_compile standalone_ocr_api.py cartorio_ocr\app.py cartorio_ocr\cli.py cartorio_ocr\config.py cartorio_ocr\schemas.py cartorio_ocr\registry_schema.py cartorio_ocr\evaluation.py services\gemini_ocr.py
python -B -m pytest -q

Resultado local validado: 9 passed.

Docker

docker build -t cartorio-ocr-pipeline .
docker run --env-file .env -p 8081:8081 cartorio-ocr-pipeline

Avaliacao da linha proposta para cartorio

Faz sentido seguir a linha: OCR local especializado + segundo leitor independente + modelo multimodal estruturador + validacao humana. Eu ajustaria assim:

1. Comecar com baseline simples: renderizacao/pre-processamento deste projeto + GeminiOCR.
2. Criar amostra ouro com paginas corrigidas manualmente.
3. Medir CER/WER por pagina e por campo, usando cartorio_ocr/evaluation.py.
4. Adicionar GLM-OCR ou MiniCPM-V/MiniCPM-o como leitor local principal.
5. Rodar DeepSeek-OCR ou outro leitor independente apenas para divergencias e conferencia.
6. Usar Qwen3-VL ou Gemma 4 para estruturar JSON, sem tratar o estruturador como fonte unica da transcricao.
7. Para manuscrito historico recorrente, treinar Kraken/eScriptorium com amostras corrigidas do proprio acervo.
8. Enviar para revisao humana qualquer campo com baixa confianca ou divergencia entre leitores.

Por que nao copiar a arquitetura antiga inteira

O projeto Brass tem uma linha antiga com Modal, Google Vision e referencias a DeepSeek-OCR. Ela e util como historico, mas nao e a melhor base principal:

• ai-pipeline/src/main.py ainda tem OCR como TODO/stub.
• STATUS_ATUAL.md registra que DeepSeek-OCR estava falhando na inicializacao e que a solucao operacional virou Gemini.
• modal_app.py mistura OCR, avaliacao, LangGraph, anotacao visual e PDF, entao e pesado demais para virar um microservico limpo.
• cloudrun-backend/services/gemini_ocr.py esta mais coeso e ja tem fallback, pre-processamento e endpoint real no backend.

Mensagem curta para Pedro

Pedro, combinado. Eu olhei o OCR que ja existe no BraSS e acho que a tua linha faz sentido para livros antigos de cartorio, com um ajuste: eu nao apostaria num unico "Gemini local" nem tentaria reaproveitar o sistema de provas como esta. O melhor e transformar a parte de OCR em um pipeline de leitura documental.

Eu testaria primeiro uma base local com pre-processamento + GLM-OCR ou MiniCPM-V/MiniCPM-o 4.5, depois um segundo leitor independente para comparar divergencias, e so entao um multimodal como Qwen3-VL ou Gemma 4 para estruturar em JSON. Para manuscrito antigo de verdade, eu colocaria Kraken/eScriptorium no plano, treinado com paginas corrigidas do proprio acervo. Isso e mais profissional do que depender de um modelo unico.

Fontes tecnicas consultadas

• FastAPI lifespan/response patterns: https://github.com/fastapi/fastapi
• Pydantic Settings: https://github.com/pydantic/pydantic-settings
• Google Gen AI Python SDK: https://github.com/googleapis/python-genai
• GLM-OCR: https://github.com/zai-org/GLM-OCR
• DeepSeek-OCR: https://github.com/deepseek-ai/DeepSeek-OCR
• MiniCPM-V/MiniCPM-o: https://github.com/OpenBMB/MiniCPM-V
• Qwen3-VL: https://github.com/QwenLM/Qwen3-VL
• Gemma 4: https://ai.google.dev/gemma/docs/core
• Kraken: https://kraken.re/5.3.0/index.html
• eScriptorium: https://escriptorium.readthedocs.io/