Aplicação de estudo para enviar PDFs e consultar seu conteúdo em português. Combina FastAPI, React, Chroma e Ollama, com contas locais, indexação por usuário e indicação dos documentos usados como contexto.
O projeto começou em outubro de 2025 como uma exploração prática de Retrieval-Augmented Generation. Em setembro de 2026, recebeu uma revisão focada em isolamento de dados, upload, rastreabilidade das fontes, testes e reprodução do ambiente. O histórico de desenvolvimento foi preservado.
A captura mostra a recusa de uma pergunta sem evidência suficiente no PDF de demonstração. As fontes exibidas em outras respostas identificam o contexto fornecido ao modelo; não constituem validação automática de cada afirmação.
- Cadastro e login com senha armazenada como hash, JWT com expiração e contas em SQLite.
- Armazenamento vetorial separado por identificador derivado do e-mail completo.
- Upload de PDFs de até 20 MiB, com validação de nome/cabeçalho, gravação em blocos e nomes temporários aleatórios.
- Extração de texto, divisão em trechos e indexação em segundo plano. O frontend acompanha o estado do processamento.
- Recuperação semântica com embeddings multilíngues, deduplicação, seleção de contexto e reranking opcional.
- Recusa antes da geração quando a recuperação não fornece contexto suficiente.
- Cache de respostas por usuário e versão do índice, métricas por etapa e avaliação lexical de perguntas de exemplo.
flowchart LR
UI[React] --> API[FastAPI + autenticação]
API --> Accounts[(SQLite: contas)]
API --> PDF[PDF: extração e divisão]
PDF --> Vectors[(Chroma por usuário)]
API --> Search[Recuperação e seleção de contexto]
Vectors --> Search
Search --> Gate{Contexto suficiente?}
Gate -->|Não| Refuse[Resposta de recusa]
Gate -->|Sim| LLM[Ollama local]
LLM --> Answer[Resposta + fontes do contexto]
Os PDFs temporários são removidos após a tentativa de indexação. O texto extraído permanece na base vetorial local. Os modelos são carregados sob demanda; importar o backend ou executar os testes básicos não baixa modelos.
Ambiente de referência: Linux/WSL, Python 3.12, Node.js 22.12+ e uv. Os arquivos de dependências do backend foram resolvidos para esse ambiente, com PyTorch em CPU. Windows nativo e outras versões de Python não foram validados nesta revisão.
Na raiz do repositório:
python3 backend/setup_dev.py
uv venv backend/.venv --python 3.12
uv pip install --python backend/.venv/bin/python -r backend/requirements.txt --torch-backend cpusetup_dev.py cria backend/.env com uma chave aleatória e preserva arquivos existentes. O backend rejeita chaves com menos de 32 caracteres.
Instale o Ollama e prepare o modelo de geração:
ollama pull llama3.2:1b
# Em outro terminal, se o serviço ainda não estiver ativo:
ollama serveInicie a API:
backend/.venv/bin/uvicorn main:app --app-dir backend --host 127.0.0.1 --port 8000O primeiro upload baixa o modelo de embeddings configurado e pode demorar mais. O modelo padrão é sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2; as operações sobre o texto acontecem localmente.
Em outro terminal, na raiz:
npm --prefix frontend ci
npm --prefix frontend run devAbra http://localhost:5173. A documentação interativa da API fica em http://127.0.0.1:8000/docs.
- Cadastre uma conta.
- Envie docs/exemplo.pdf, um guia fictício de um clube de leitura.
- Aguarde o status
finalizado. - Pergunte “Em que dia e horário o clube se reúne?” ou “Até quantos livros posso levar para troca?”.
- Experimente “Qual é o telefone da biblioteca?”, uma informação ausente no documento.
O texto original do PDF está em docs/exemplo.txt. A qualidade e a latência das respostas dependem do modelo de geração, do equipamento e dos documentos enviados.
Edite backend/.env. Os valores principais são:
| Variável | Padrão / finalidade |
|---|---|
SECRET_KEY |
Gerada por setup_dev.py; assina os tokens de acesso |
OLLAMA_MODEL |
llama3.2:1b |
OLLAMA_BASE_URL |
http://127.0.0.1:11434 |
EMBEDDING_MODEL |
sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 |
FRONTEND_ORIGINS |
http://localhost:5173 |
MAX_UPLOAD_BYTES |
20971520 (20 MiB) |
RAG_SCORE_FLOOR / RAG_SCORE_THRESHOLD |
0.35; limiares heurísticos, não probabilidades de acerto |
RAG_RERANK_MODEL |
Vazio: reranker desativado |
USERS_DB_PATH |
backend/local/users.sqlite3 |
UPLOAD_DIRECTORY / CHROMA_DB_DIRECTORY |
backend/local/uploads / backend/local/vectors |
O diretório backend/local/ e os arquivos .env ficam fora do versionamento. Se trocar a porta da API, crie frontend/.env.local com VITE_API_URL=http://127.0.0.1:NOVA_PORTA. Ao trocar o modelo de embeddings, use uma base vetorial nova e indexe os PDFs novamente.
Instalações antigas: a revisão substituiu users.json por SQLite e mudou os identificadores das bases. Cadastre as contas novamente e reenvie os PDFs. As bases antigas não são importadas automaticamente, pois os identificadores anteriores podiam representar mais de um e-mail.
Testes rápidos, sem Ollama, modelos de embeddings ou banco externo:
uv pip install --python backend/.venv/bin/python -r backend/requirements-test.txt
backend/.venv/bin/python -m pytest backend
backend/.venv/bin/python backend/_localrag_smoke.py
backend/.venv/bin/python backend/_evaluation_smoke.py
npm --prefix frontend run buildA suíte cobre autenticação, cadastro concorrente, separação de contas e caches, upload, atendimento concorrente, recusa de contexto fraco e correspondência entre fontes e contexto. Com as dependências completas instaladas, também executa a integração de PDF + Chroma, incluindo reenvio idempotente; esse teste usa embeddings determinísticos. O CI executa os testes leves e o build TypeScript/Vite.
Para executar a avaliação com o modelo real, use uma conta que já tenha indexado o PDF de exemplo:
backend/.venv/bin/python backend/run_evaluation.py \
--user seu_email@exemplo.com \
--dataset backend/eval_samples/sample_questions.json \
--output backend/local/avaliacao.jsonEssa avaliação mede presença de termos e existência de fontes. Ela não mede factualidade, precisão das citações nem qualidade geral do RAG. O conjunto pequeno é uma demonstração reproduzível, não um benchmark representativo. A exportação inclui perguntas, respostas e metadados das fontes para inspeção manual.
- Execução local: permite explorar recuperação e geração sem enviar os PDFs a uma API de LLM. Exige recursos para executar os modelos.
- SQLite e um processo de API: simplificam o ambiente de estudo. Caches e estados dos jobs ficam em memória; não há coordenação entre múltiplos workers nem retomada de jobs após reinício.
- Rastreabilidade: as fontes correspondem aos trechos enviados ao modelo. Uma resposta ainda pode interpretar mal esses trechos ou conter informações incorretas.
- Recuperação: os scores absolutos são preservados. Os limiares precisam ser avaliados com o corpus escolhido; a revisão verificou a recuperação no pequeno documento de exemplo, sem estabelecer uma calibração universal.
- Escopo da interface: o histórico visual não é enviado ao modelo e se perde ao recarregar a página. Não há listagem/exclusão de documentos, OCR, streaming ou recuperação de senha.
- Disponibilização: o projeto continua sendo um protótipo local. Rate limiting, quotas, gestão de contas e operação em produção permanecem fora do escopo desta revisão.
A revisão validou extração, embeddings, Chroma, recusa por falta de contexto e testes com geração simulada. Não inclui uma avaliação de qualidade com o modelo Ollama real.
backend/
main.py API e pipeline RAG
auth_store.py Contas em SQLite
evaluation.py Avaliação lexical
tests/ Testes de regressão e integração local
requirements*.in/.txt Dependências declaradas e versões resolvidas
frontend/src/ Interface React/TypeScript
docs/ PDF fictício, texto e captura da interface
.github/workflows/ Testes e build
