Metadata-Version: 2.4
Name: DeepRead.Monkai
Version: 2.3.0
Summary: Biblioteca para extração inteligente de documentos PDF com IA
Author-email: Monkai <contato@monkai.com.br>
License: MIT
Project-URL: Homepage, https://github.com/BeMonkAI/deepread
Project-URL: Documentation, https://github.com/BeMonkAI/deepread#readme
Project-URL: Repository, https://github.com/BeMonkAI/deepread
Project-URL: Issues, https://github.com/BeMonkAI/deepread/issues
Keywords: pdf,extraction,ai,ocr,document,llm,openai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: llama-index-readers-file>=0.1.0
Requires-Dist: llama-index-core>=0.10.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: PyMuPDF>=1.24.0
Requires-Dist: requests>=2.28.0
Requires-Dist: tenacity>=8.0.0
Provides-Extra: ocr
Requires-Dist: azure-ai-vision-imageanalysis>=1.0.0; extra == "ocr"
Requires-Dist: Pillow>=10.0.0; extra == "ocr"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: all
Requires-Dist: deepread[dev,ocr]; extra == "all"

# DeepRead

**Biblioteca Python para extracao inteligente de documentos PDF com IA**

[![PyPI](https://img.shields.io/pypi/v/DeepRead.Monkai.svg)](https://pypi.org/project/DeepRead.Monkai/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/BeMonkAI/deepread/actions/workflows/ci.yml/badge.svg)](https://github.com/BeMonkAI/deepread/actions/workflows/ci.yml)
[![Quality Seal](https://img.shields.io/badge/Claude_AI-Quality_Certified-blue)](docs/certificacao-qualidade.md)

---

## 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

```bash
pip install DeepRead.Monkai
```

Com OCR (Azure AI Vision):

```bash
pip install DeepRead.Monkai[ocr]
```

Desenvolvimento:

```bash
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**

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

### 2. Processar Documento

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

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

---

## Azure OpenAI

```bash
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"
```

```python
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) |

---

## Modelos Disponiveis

```python
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](docs/instalacao.md) | Guia de instalacao e configuracao |
| [Guia Rapido](docs/guia-rapido.md) | Comece em 5 minutos |
| [Autenticacao](docs/autenticacao.md) | Sistema de tokens |
| [Perguntas](docs/perguntas.md) | Configuracao de perguntas e extracao |
| [Classificacao](docs/classificacao.md) | Classificacao de documentos |
| [OCR](docs/ocr.md) | Reconhecimento optico de caracteres |
| [Schemas](docs/schemas.md) | Modelos de dados e estruturas |
| [API Reference](docs/api-reference.md) | Referencia completa da API |
| [Exemplos](docs/exemplos/) | Exemplos praticos (01-07) |
| [Certificacao](docs/certificacao-qualidade.md) | 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](docs/certificacao-qualidade.md) | [Ver certificado HTML](AUDIT_CERTIFICATE.html)

---

## Suporte

- **Email:** contato@monkai.com.br
- **Site:** [www.monkai.com.br](https://www.monkai.com.br)

---

**Desenvolvido por [Monkai](https://www.monkai.com.br)**
