DeepRead

Biblioteca Python para extracao inteligente de documentos PDF com IA

Caracteristicas

• Autenticacao por Token - HMAC-SHA256 com timing-safe validation
• Extracao Inteligente - Extrai informacoes de PDFs usando LLMs (OpenAI / Azure OpenAI)
• OCR Automatico - Detecta e processa documentos escaneados (Azure AI Vision)
• Deteccao por Pagina - Classifica o PDF em text, mixed ou image e roda OCR apenas nas paginas sem texto nativo
• Imagem como Entrada - PNG, JPEG, TIFF, BMP e GIF viram PDF de 1 pagina automaticamente
• Structured Output - Respostas tipadas com Pydantic
• Async + Sync - APIs sincrona e assincrona com batch processing
• Resiliencia - Retry com backoff exponencial e circuit breaker
• Cache - Cache LRU com TTL para evitar reprocessamento
• Page Range - Filtre paginas especificas por posicao (inicio/fim)
• Streaming - Modo lazy para economia de memoria
• Tracking de Custos - Monitore tokens e custos por requisicao

Arquitetura

Ver ARCHITECTURE.md para as decisoes de desenho: por que a pagina e a unidade de processamento, por que nao chunks com embedding, e onde isso deixa de valer.

A conta medida, com gemini-2.5-flash: filtrar por keyword envia 731 tokens em vez de 12.931 num contrato de 40 paginas (94% menos), e rodar OCR so nas paginas sem texto nativo corta 59% num documento com 5 escaneadas em 20 — uma pagina via visao custa ~4,8x uma pagina de texto.

Instalacao

pip install DeepRead.Monkai

Com OCR (Azure AI Vision):

pip install DeepRead.Monkai[ocr]

Desenvolvimento:

pip install DeepRead.Monkai[dev]

Uso Rapido

1. Obter Token de Acesso

O token de acesso e fornecido pela equipe Monkai. Para solicitar: contato@monkai.com.br

export DEEPREAD_API_TOKEN="dr_seu_token_fornecido_pela_monkai"
export OPENAI_API_KEY="sk-..."

2. Processar Documento

import os
from deepread import DeepRead, Question, QuestionConfig
from pydantic import BaseModel, Field

class ExtractionResponse(BaseModel):
    valor: str = Field(description="Valor extraido")
    unidade: str = Field(default="", description="Unidade de medida")
    confianca: float = Field(default=1.0, ge=0, le=1)

question = Question(
    config=QuestionConfig(id="quantidade", name="Extracao de Quantidade"),
    system_prompt="Voce e um especialista em extracao de dados de documentos.",
    user_prompt="Analise o texto e extraia a quantidade mencionada.\n\nTexto:\n{texto}",
    keywords=["quantidade", "litros", "volume", "total"],
    response_model=ExtractionResponse
)

dr = DeepRead(
    api_token=os.getenv("DEEPREAD_API_TOKEN"),
    openai_api_key=os.getenv("OPENAI_API_KEY"),
    model="gpt-5.1",
    verbose=True
)

dr.add_question(question)
result = dr.process("documento.pdf")

print(f"Resposta: {result.get_answer('quantidade')}")
print(f"Tokens: {result.total_metrics.tokens}")
print(f"Custo: ${result.total_metrics.cost_usd:.4f}")

3. Multiplas Perguntas com Page Range

from deepread import PageRange

dr.add_questions([
    Question(
        config=QuestionConfig(id="preco", name="Preco"),
        user_prompt="Extraia o preco: {texto}",
        keywords=["preco", "valor", "R$"],
        page_range=PageRange(start=1, end=5, from_position="start")
    ),
    Question(
        config=QuestionConfig(id="conclusao", name="Conclusao"),
        user_prompt="Extraia a conclusao: {texto}",
        keywords=["conclusao", "resultado"],
        page_range=PageRange(start=1, end=3, from_position="end")
    ),
])

result = dr.process("documento.pdf")
for r in result.results:
    print(f"{r.question_name}: {r.answer}")

4. Classificacao de Documentos

from deepread import Classification
from typing import Literal

class ClassificacaoDoc(BaseModel):
    classificacao: Literal["APROVADO", "REPROVADO", "REVISAR"]
    justificativa: str
    confianca: float = Field(ge=0, le=1)

classification = Classification(
    system_prompt="Voce e um classificador de documentos.",
    user_prompt="Baseado nos dados extraidos, classifique o documento:\n\n{dados}",
    response_model=ClassificacaoDoc
)

dr.set_classification(classification)
result = dr.process("documento.pdf", classify=True)
print(f"Classificacao: {result.classification}")

5. Processamento em Lote

from pathlib import Path

docs = list(Path("documentos/").glob("*.pdf"))
results = dr.process_batch(docs, classify=True, max_workers=4)

for r in results:
    print(f"{r.document.filename}: {r.get_answer('preco')}")

6. API Assincrona

import asyncio

async def main():
    dr = DeepRead(
        api_token=os.getenv("DEEPREAD_API_TOKEN"),
        openai_api_key=os.getenv("OPENAI_API_KEY"),
    )
    dr.add_question(question)

    result = await dr.process_async("documento.pdf")
    print(result.get_answer("quantidade"))

    results = await dr.process_batch_async(docs, max_concurrency=5)

asyncio.run(main())

7. Cache e Resiliencia

dr = DeepRead(
    api_token=os.getenv("DEEPREAD_API_TOKEN"),
    openai_api_key=os.getenv("OPENAI_API_KEY"),
    enable_cache=True,
    cache_ttl=3600,
    max_retries=3,
    circuit_breaker=True,
    circuit_breaker_threshold=5,
    circuit_breaker_timeout=60,
    streaming=True,
)

result = dr.process("documento.pdf")
print(f"Cache stats: {dr.cache_stats}")

8. Multiplos Tipos de Input

result = dr.process("documento.pdf")

result = dr.process("https://exemplo.com/doc.pdf")

with open("doc.pdf", "rb") as f:
    result = dr.process(f.read(), filename="doc.pdf")

import io
buffer = io.BytesIO(pdf_bytes)
result = dr.process(buffer, filename="doc.pdf")

Imagens (PNG, JPEG, TIFF, BMP, GIF) tambem sao aceitas em qualquer um dos formatos acima: viram um PDF de 1 pagina automaticamente. Como nao tem texto nativo, o conteudo so e extraido com OCR ativo:

dr = DeepRead(api_token=..., openai_api_key=..., ocr_fallback="auto")
result = dr.process("foto_do_contrato.jpg")

9. Deteccao Automatica de Tipo de Pagina

O DeepRead perfila o PDF pagina a pagina e classifica o documento:

O resultado informa quantas paginas custaram visao:

result = dr.process("contrato.pdf")
print(result.document.doc_type)          # "mixed"
print(result.document.pages_needing_ocr) # 5  (de 20 paginas)

Num documento de 20 paginas com 5 escaneadas, sao 5 chamadas de visao, nao 20: as 15 paginas com texto nativo sao lidas direto do PDF.

Controle manual. A deteccao e automatica, mas voce decide o que fazer com ela:

# nao gastar visao nunca (paginas escaneadas ficam sem conteudo)
dr = DeepRead(..., ocr_fallback="off")      # default

# usar visao quando o Azure OCR falhar ou nao estiver configurado
dr = DeepRead(..., ocr_fallback="auto")

# ignorar o Azure OCR e ir direto na visao
dr = DeepRead(..., ocr_fallback="force")

# ajustar a sensibilidade da deteccao (default: 100 caracteres)
dr = DeepRead(..., ocr_fallback="auto", min_chars_per_page=250)

Suba min_chars_per_page quando a pagina escaneada tiver cabecalho/rodape em texto (o pouco texto nativo faria a pagina passar como legivel); desca para gastar menos visao aceitando paginas com pouco texto.

10. Modos de Extracao e Perguntas em Lote

Como o conteudo chega ao modelo, e quantas perguntas por chamada:

# default: extrai texto, filtra por keyword, envia texto
dr = DeepRead(api_token=..., openai_api_key=...)

# envia o documento ao modelo multimodal (preserva layout, nao paga OCR)
dr = DeepRead(..., extraction_mode="direct")

# indexa por embedding e envia so os trechos proximos da pergunta
dr = DeepRead(..., extraction_mode="rag", rag_top_k=5)

# responde ate 10 perguntas por chamada de LLM
dr = DeepRead(..., questions_per_call=10)

questions_per_call agrupa apenas perguntas com o mesmo contexto (mesmas keywords e page_range) e envia o texto do documento uma vez em vez de uma por pergunta. Em 20 perguntas sobre um contrato de 40 paginas isso corta 91% do custo. Em troca, as perguntas do lote falham juntas, por isso o default e 1.

Detalhes e numeros em ARCHITECTURE.md, e a comparacao medida das cinco tecnicas sobre documentos reais em docs/estudo-tecnicas.md.

CLI

CLI machine-friendly para automação e uso por agentes de IA. Toda saída é JSON em stdout, erros em stderr, e o exit code reflete sucesso (0) ou falha (≥1).

Instalação

pip install "DeepRead.Monkai[cli]"

Comandos

Exemplos

# Versão
deepread version

# Listar modelos disponíveis
deepread models

# Listar schemas pré-construídos
deepread schemas

# Extração one-shot com schema pré-construído
export DEEPREAD_API_TOKEN=dr_...
export OPENAI_API_KEY=sk-...
deepread extract documento.pdf --schema DadosContrato

# Extração one-shot com prompt customizado
deepread extract documento.pdf \
  --prompt "Extraia o valor total do documento: {texto}" \
  --keywords "valor,total,R$" \
  --pages 1-5

# Gerar config YAML para uso recorrente
deepread init config.yaml --schema DadosContrato

# Executar com config (single)
deepread run config.yaml documento.pdf -o resultado.json

# Executar em lote (diretório)
deepread run config.yaml ./documentos/ -o resultados.csv -f csv

Flags do extract

Configuração via YAML

Para usar Azure OpenAI ou customizar parâmetros mais finos, rode deepread init para gerar um config base com seção auth que resolve ${ENV_VAR} automaticamente:

deepread:
  model: balanced
  ocr: off
  max_retries: 3
  enable_cache: false

auth:
  api_token: ${DEEPREAD_API_TOKEN}
  openai_api_key: ${OPENAI_API_KEY}
  # Para Azure OpenAI:
  # provider: azure
  # azure_api_key: ${AZURE_API_KEY}
  # azure_endpoint: https://seu-recurso.openai.azure.com
  # azure_deployment: gpt-4o
  # azure_api_version: 2024-02-15-preview

questions:
  - id: extracao
    name: Extração
    prompt: "Extraia as informações principais: {texto}"
    schema: DadosContrato

Exit codes

Azure OpenAI

export OPENAI_PROVIDER=azure
export AZURE_API_KEY="sua-chave-azure"
export AZURE_API_ENDPOINT="https://seu-recurso.openai.azure.com"
export AZURE_API_VERSION="2024-02-15-preview"
export AZURE_DEPLOYMENT_NAME="gpt-4o"

dr = DeepRead(
    api_token=os.getenv("DEEPREAD_API_TOKEN"),
    provider="azure",
    azure_api_key="sua-chave-azure",
    azure_endpoint="https://seu-recurso.openai.azure.com",
    azure_deployment="gpt-4o",
)

Google Gemini

DeepRead supports Google Gemini via the AI Studio API. Install the extra and set your API key:

pip install "DeepRead.Monkai[google]"
export GOOGLE_API_KEY="your-key-here"

Use provider="google":

from deepread import DeepRead

dr = DeepRead(
    api_token="dr_xxx",
    provider="google",
    model="balanced",  # -> gemini-2.5-flash
)
result = dr.process("document.pdf")

Model aliases for Google:

All DeepRead features — structured output (Pydantic schemas), classification, OCR vision fallback, async, streaming, and cost tracking — work identically on Google.

xAI Grok

DeepRead supports xAI Grok through its OpenAI-compatible endpoint. No extra install is needed — Grok reuses the bundled OpenAI SDK; just set your API key:

export XAI_API_KEY="your-key-here"   # GROK_API_KEY also accepted as fallback

Use provider="grok":

from deepread import DeepRead

dr = DeepRead(
    api_token="dr_xxx",
    provider="grok",
    model="balanced",  # -> grok-3
)
result = dr.process("document.pdf")

Point at a custom/proxy endpoint with grok_base_url= or the XAI_BASE_URL env var (default https://api.x.ai/v1):

dr = DeepRead(
    api_token="dr_xxx",
    provider="grok",
    grok_api_key="xai-...",
    grok_base_url="https://gateway.internal/v1",
    model="complete",  # -> grok-4
)

CLI:

deepread extract document.pdf --provider grok --grok-key "$XAI_API_KEY" --model balanced

Model aliases for Grok:

All DeepRead features — structured output (Pydantic schemas), classification, OCR vision fallback, async, streaming, and cost tracking — work identically on Grok.

Modelos Disponiveis

print(DeepRead.available_models())
# {
#     "fast": "gpt-4.1",
#     "balanced": "gpt-5.1",
#     "complete": "gpt-5-2025-08-07",
#     "economic": "gpt-5-mini-2025-08-07"
# }

API Reference

DeepRead

DeepRead Constructor

Question

PageRange

ProcessingResult

DocumentMetadata

ProcessingMetrics

Estrutura do Projeto

deepread/
├── __init__.py          # Exports principais
├── reader.py            # Classe DeepRead (sync + async)
├── config.py            # Modelos, precos, configuracoes
├── utils.py             # PDF loading, filtragem, metadata
├── ocr.py               # Azure AI Vision OCR
├── cache.py             # Cache LRU com TTL
├── resilience.py        # Retry + Circuit Breaker
├── exceptions.py        # Excecoes customizadas
├── auth/
│   ├── __init__.py
│   ├── token.py         # HMAC-SHA256 token validation
│   └── exceptions.py    # Excecoes de autenticacao
└── models/
    ├── __init__.py
    ├── question.py      # Question, QuestionConfig, PageRange
    ├── result.py        # Result, ProcessingResult, Metrics
    ├── classification.py # Classification
    └── schemas.py       # Schemas de exemplo (DadosContrato, etc)

Documentacao

Certificacao de Qualidade

Este projeto foi auditado e certificado pelo Claude AI Quality Seal.

Classificacao: PROFISSIONAL Serial: DR-CQA-DE8364E7-116B6022-D40E375D-42BB4E3B

Ver certificado completo | Ver certificado HTML

Suporte

• Email: contato@monkai.com.br
• Site: www.monkai.com.br

Desenvolvido por Monkai