--- 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 `...` 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."*