DeepRead.Monkai 4.1.0

Biblioteca para extração inteligente de documentos PDF com IA

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)
• 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

---

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: [e-mail]

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")

---

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

Comando	Descrição
version	Mostra a versão instalada
models	Lista modelos LLM disponíveis com pricing
schemas	Lista schemas pré-construídos com seus campos
extract <pdf>	Extração one-shot de um único PDF
run <config> <target>	Executa extração com YAML config (single ou batch)
init <output>	Gera um arquivo YAML de configuração

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

Flag	Env var	Descrição
--token	DEEPREAD_API_TOKEN	Token do DeepRead
--api-key	OPENAI_API_KEY	Chave OpenAI
--schema / -s	—	Nome de schema pré-construído
--prompt / -p	—	Prompt customizado (deve conter {texto})
--model / -m	—	Modelo: fast/balanced/complete/economic ou nome direto
--ocr	—	OCR mode: off/auto/force
--keywords / -k	—	Keywords separadas por vírgula
--pages	—	Range de páginas (1-5 ou last-3)
--format / -f	—	Saída: json/csv/text
--verbose / -v	—	Logs detalhados em stderr
--quiet / -q	—	Suprime stderr

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

Code	Significado
0	Sucesso
1	Falha genérica
2	Erro de configuração (chave/token ausente)
3	Arquivo não encontrado
4	Erro de execução (rede, API, etc.)

---

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",
)

Parametro	OpenAI	Azure OpenAI
provider	"openai" (default)	"azure"
openai_api_key	Obrigatorio	Nao usado
azure_api_key	Nao usado	Obrigatorio
azure_endpoint	Nao usado	Obrigatorio
azure_deployment	Nao usado	Obrigatorio
model	Nome do modelo	Ignorado (usa deployment)

---

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:

Alias	Gemini model
fast	gemini-2.5-flash-lite
balanced	gemini-2.5-flash
complete	gemini-2.5-pro
economic	gemini-2.5-flash-lite

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:

Alias	Grok model
fast	grok-3-mini
balanced	grok-3
complete	grok-4
economic	grok-3-mini

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

Metodo	Descricao
add_question(question)	Adiciona uma pergunta
add_questions(questions)	Adiciona multiplas perguntas
remove_question(id)	Remove uma pergunta
clear_questions()	Remove todas as perguntas
set_classification(config)	Configura classificacao
process(document)	Processa um documento (sync)
process_async(document)	Processa um documento (async)
process_batch(documents, max_workers)	Processa lote (sync, com ThreadPool)
process_batch_async(documents, max_concurrency)	Processa lote (async, com Semaphore)
clear_cache()	Limpa o cache
cache_stats	Retorna hits/misses/size do cache
available_models()	Lista modelos disponiveis
create_question(...)	Factory method para Question

DeepRead Constructor

Parametro	Tipo	Default	Descricao
api_token	str	-	Token de autenticacao (obrigatorio)
openai_api_key	str	env	Chave API OpenAI
model	str	gpt-5.1	Modelo LLM
verbose	bool	False	Logs detalhados
max_retries	int	3	Retries para erros transientes
enable_cache	bool	False	Habilita cache LRU
cache_ttl	int	3600	TTL do cache em segundos
streaming	bool	False	Modo lazy (economia de memoria)
circuit_breaker	bool	False	Habilita circuit breaker
circuit_breaker_threshold	int	5	Falhas para abrir circuito
circuit_breaker_timeout	int	60	Segundos para recovery
max_file_size_mb	float	50	Limite de tamanho do arquivo
max_pages	int	500	Limite de paginas
provider	str	openai	Provider: openai ou azure

Question

Campo	Tipo	Descricao
config	QuestionConfig	Configuracao basica (id, name)
system_prompt	str	Prompt de sistema
user_prompt	str	Template do prompt (use {texto})
keywords	list[str]	Keywords para filtrar paginas
page_range	PageRange	Range de paginas (opcional)
response_model	BaseModel	Modelo Pydantic (opcional)

PageRange

Campo	Tipo	Descricao
start	int	Pagina inicial (1-indexed)
end	int	Pagina final (None = ate o fim)
from_position	str	"start" ou "end"

ProcessingResult

Campo	Tipo	Descricao
document	DocumentMetadata	Metadados do documento
results	list[Result]	Resultados por pergunta
classification	dict	Classificacao (se aplicavel)
total_metrics	ProcessingMetrics	Metricas totais

ProcessingMetrics

Campo	Tipo	Descricao
time_seconds	float	Tempo de processamento
tokens	int	Total de tokens
prompt_tokens	int	Tokens do prompt
completion_tokens	int	Tokens da resposta
cost_usd	float	Custo em USD
model	str	Modelo utilizado

---

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

Documento	Descricao
Instalacao	Guia de instalacao e configuracao
Guia Rapido	Comece em 5 minutos
Autenticacao	Sistema de tokens
Perguntas	Configuracao de perguntas e extracao
Classificacao	Classificacao de documentos
OCR	Reconhecimento optico de caracteres
Schemas	Modelos de dados e estruturas
API Reference	Referencia completa da API
Exemplos	Exemplos praticos (01-07)
Certificacao	Certificado de qualidade

---

Certificacao de Qualidade

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

Dimensao	Score
Seguranca	8.7/10
Usabilidade	8.2/10
Escalabilidade	7.8/10
Qualidade de Codigo	8.0/10
Global	8.18/10

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

Ver certificado completo | Ver certificado HTML

---

Suporte

• Email: [e-mail]
• Site: www.monkai.com.br

---

Desenvolvido por Monkai