File size: 6,257 Bytes
b0e0c29
68e8c03
 
 
 
b6eb13c
b0e0c29
 
 
68e8c03
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b6eb13c
68e8c03
b6eb13c
 
 
68e8c03
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
---
title: DocuMind AI
emoji: 📄
colorFrom: blue
colorTo: indigo
sdk: static
pinned: false
---

# 📄 DocuMind AI

Aplicação de **RAG (Retrieval-Augmented Generation)** com **embeddings locais** e arquitetura **BYOK (Bring Your Own Key)**, permitindo o envio de documentos PDF e perguntas em linguagem natural com respostas fundamentadas exclusivamente nos arquivos enviados e citação de fontes.

---

## 🧠 O que é RAG?

**Retrieval-Augmented Generation (Geração Aumentada por Recuperação)** combina **busca semântica em uma base vetorial** com **Modelos de Linguagem (LLMs)**:

1. **Indexação:** os documentos são convertidos em vetores numéricos (*embeddings*) e armazenados no ChromaDB.
2. **Recuperação:** apenas os trechos mais relevantes para a pergunta são recuperados.
3. **Geração:** os trechos recuperados são enviados à LLM como contexto fechado, reduzindo alucinações.

---

## 🏗️ Arquitetura e Fluxo de Dados

```text
[PDFs] ─▶ document_loader.py ─▶ text_splitter.py ─▶ embeddings.py (local) ─▶ vector_store.py (ChromaDB)
                                                                                      │
[Pergunta] ─▶ embeddings.py (local) ──────────────▶ retriever.py (Top 3-5) ───────────┘
                                                            │
                                                            ▼
[Resposta + Fontes] ◀── app.py (Streamlit) ◀── rag_pipeline.py ◀── llm.py (BYOK: Gemini / Groq)
```

### Embeddings Locais (`sentence-transformers/all-MiniLM-L6-v2`)
- Os vetores são gerados **100% localmente na CPU** via `PyTorch` e `Sentence Transformers` (**nenhuma API Key é exigida para embeddings**).
- O mesmo modelo (`all-MiniLM-L6-v2`, 384 dimensões) é usado na indexação e nas consultas, garantindo compatibilidade dimensional.
- Em `app.py`, o modelo é carregado **uma única vez por processo** com `@st.cache_resource`. Os pesos (~90 MB) são baixados apenas na primeira inicialização e reaproveitados do cache local (`SENTENCE_TRANSFORMERS_HOME` ou cache padrão do Hugging Face).

### Modelos e APIs Utilizados
- **Embeddings:** `sentence-transformers/all-MiniLM-L6-v2` (local, sem chave).
- **LLM Primário:** Google Gemini API (`google-genai`, padrão `gemini-2.5-flash`, configurável via `GEMINI_MODEL`).
- **LLM Alternativo / Fallback:** Groq API via REST (`httpx`, padrão `openai/gpt-oss-120b`, configurável via `GROQ_MODEL`).

---

## 🔑 Modos de Autenticação (BYOK)

O visitante utiliza suas próprias credenciais diretamente na barra lateral, **sem depender de chaves do proprietário**:

1. **Modo Gemini:** solicita apenas `GEMINI_API_KEY` e utiliza a Google Gemini API.
2. **Modo Groq:** solicita apenas `GROQ_API_KEY` e utiliza a Groq API.
3. **Modo Gemini + fallback Groq:** solicita ambas as chaves; o Gemini atua como provedor primário e a Groq é acionada automaticamente em **falhas temporárias elegíveis** (`429`, `5xx`, *timeout* ou erro de rede), exibindo aviso visual na resposta quando o fallback ocorre.

---

## 🔒 Privacidade, Segurança e Isolamento

- **Credenciais em memória:** as chaves digitadas permanecem apenas na memória da sessão (`st.session_state`), nunca são gravadas em disco, no ChromaDB, em logs ou no histórico de chat, e podem ser removidas a qualquer momento pelo botão **Limpar credenciais**.
- **Sanitização de erros:** possíveis trechos de chaves ou headers `Bearer` são mascarados antes de qualquer exibição.
- **Isolamento multiusuário:** cada sessão recebe um identificador criptográfico (`secrets.token_urlsafe`) e sua própria coleção no ChromaDB (com diretório temporário dedicado quando executado no Hugging Face Spaces via `SPACE_ID`), evitando contenção de escrita e vazamento de documentos entre visitantes.
- **Proteção contra Prompt Injection:** os trechos recuperados são isolados entre tags `<documentos>...</documentos>` e o modelo é instruído a ignorar comandos embutidos nos PDFs.

---

## 📦 Instalação e Execução Local

1. Acesse a pasta do projeto:
   ```bash
   cd documind-ai
   ```

2. Crie e ative um ambiente virtual:
   ```bash
   python -m venv .venv
   # Windows (PowerShell)
   .venv\Scripts\Activate.ps1
   # Linux / macOS
   source .venv/bin/activate
   ```

3. Instale as dependências:
   ```bash
   pip install -r requirements.txt
   ```

4. *(Opcional)* Copie `.env.example` para `.env` caso queira definir `GEMINI_MODEL`, `GROQ_MODEL` ou `CHROMA_PERSIST_DIR`:
   ```bash
   cp .env.example .env
   ```

5. Execute a aplicação:
   ```bash
   streamlit run app.py
   ```

---

## 🧪 Como Executar os Testes

A suíte utiliza `pytest` com *mocks* para os provedores externos e embeddings locais, validando carregamento de PDFs, chunking, modos BYOK, fallback, isolamento entre sessões, concorrência e sanitização de logs:

```bash
pytest -v
```

---

## 🚀 Publicação Estática no Hugging Face Spaces

- O repositório utiliza **`sdk: static`** no cabeçalho YAML para servir a página de apresentação (`index.html`) junto com todo o código-fonte em Python.
- **Aviso:** a demonstração interativa em Streamlit (`app.py`) **não** é executada no Space estático; para usar a interface interativa, siga as instruções de **Instalação e Execução Local** acima.
- **Arquitetura preparada para nuvem:** o código em `app.py` e `src/` já contempla isolamento por sessão (`SPACE_ID`), arquitetura BYOK em memória e limite de **20 MB por arquivo PDF**.

---

## 💬 Exemplos de Perguntas e Respostas

Supondo o envio de um PDF com o **Manual de Estágio** ou **Documentação Técnica**:

- **Pergunta:** *"Quais são os requisitos obrigatórios para o estágio?"*
  - **Resposta:** *"De acordo com o documento enviado, é necessário estar regularmente matriculado, possuir conhecimentos em Python e disponibilidade de 30 horas semanais."*
  - **Fontes consultadas:** `manual_estagio.pdf` — Página `2`

- **Pergunta:** *"Qual é a previsão do tempo para amanhã?"* *(informação ausente nos PDFs)*
  - **Resposta:** *"Não encontrei informações suficientes nos documentos enviados para responder a essa pergunta."*