AllerCheck

Plataforma de perguntas e respostas com RAG (Retrieval-Augmented Generation) para farmacovigilância. Chat inteligente com reescrita de queries, reranking semântico, comparação de LLM vs SLM (local), e avaliação automática.

Este repositório é composto por:

1. api/: FastAPI com autenticação JWT, chat com streaming, RAG com múltiplos provedores (OpenAI, Gemini, Ollama).
2. web/: Next.js com login, histórico de conversas e interface de chat em tempo real.
3. docker-compose.yml: ambiente local com db, pgadmin, api, web, ingest-worker e ollama.

Visão Geral

Fluxo principal:

1. Usuario autentica por email/senha ou Google.
2. Frontend cria ou seleciona uma conversa.
3. Frontend envia pergunta para POST /chat (via rotas proxy em web/app/api/*).
4. API consulta historico, monta contexto RAG e retorna resposta em streaming.
5. Mensagens sao persistidas no PostgreSQL.

Arquitetura

Browser (Next.js UI)
   |
   | HTTP (rotas app/api/*)
   v
Web Container (Next.js)
   |
   | HTTP interno
   v
API Container (FastAPI)
   |\
   | \__ PostgreSQL (usuarios, conversas, mensagens)
   |
   \____ OpenAI + Pinecone (RAG)
         \___ Google tokeninfo (login Google)

Ingestao assincrona (servico separado): ingest-worker

Stack Tecnológica

• Backend: Python 3.11, FastAPI, SQLAlchemy, LangChain, Pinecone, OpenAI, Gemini, Ollama (local).
• Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS, shadcn/ui.
• Banco: PostgreSQL 16.
• LLM Locais: Ollama (Docker) com suporte a GPU NVIDIA.
• Avaliação: RAGAS com múltiplos juízes (GPT-4o-mini, Gemini, Claude Haiku, Ollama).
• Infra: Docker Compose.
• Auth: JWT + Google Identity Services.

Pré-requisitos

1. Docker e Docker Compose.
2. Chaves de API (obrigatórias): OpenAI, Gemini (ou ambas conforme config), Pinecone.
3. OAuth Client ID do Google (opcional, recomendado para login social).
4. GPU NVIDIA (opcional, para acelerar Ollama local).

Setup Rápido (Docker)

1. Criar o arquivo de ambiente na raiz:

cp .env.example .env

2. Preencher no .env apenas as variáveis obrigatórias:

   • OPENAI_API_KEY (ou GEMINI_API_KEY conforme REWRITE_PROVIDER/ANSWER_PROVIDER)
   • PINECONE_API_KEY
   • JWT_SECRET_KEY
   • GOOGLE_CLIENT_ID

   Todas as outras variáveis já têm valores sensatos no .env.example.

3. Subir os serviços:

docker compose build --no-cache
docker compose up -d

4. Acessar:

• Web: http://localhost:3000
• API Swagger: http://localhost:8000/docs
• pgAdmin: http://localhost:5050
• Ollama (local): http://localhost:11434

Nota: O arquivo api/config.yaml é deprecated. Use apenas .env para configuração.

Servico de Ingestao

A indexacao RAG roda no servico ingest-worker, separado da API.

• Intervalo padrao: INGEST_INTERVAL_SECONDS=7200 (2h).
• Logs em tempo real:

docker compose logs -f ingest-worker

• Execucao manual:

docker compose run --rm ingest-worker python ingestion/ingest_documents.py

Observacoes importantes:

• A origem padrao da ingestao e api/docs.
• A ingestao processa todos os arquivos .pdf dessa pasta (incluindo subpastas).
• Auditorias e manifestos sao salvos em api/logs/.

Variaveis de Ambiente (Raiz)

Arquivo: .env

• DATABASE_URL: conexao com PostgreSQL usada pela API e pelo worker.
• JWT_SECRET_KEY: segredo de assinatura JWT.
• GOOGLE_CLIENT_ID: client id OAuth consumido pela API e injetado no build do web.

Login com Google (Checklist)

No Google Cloud Console:

1. Adicionar http://localhost:3000 em Authorized JavaScript origins.
2. Usar o mesmo client id em GOOGLE_CLIENT_ID.

Testes

Backend

A suite conta com 81 testes distribuídos em 6 arquivos, com cobertura total de ~77%, sem depender do Docker (banco substituído por SQLite em memória via monkeypatch).

Arquivo	Tipo	Testes	O que cobre
test_auth.py	Integração	11	Registro, login, tokens, validação de campos
test_conversations.py	Integração	10	CRUD de conversas, isolamento por usuário
test_chat.py	Integração	9	Fluxo de chat, HyDE on/off, streaming, avaliação
test_auth_utils.py	Unitário	6	Hash de senha, JWT (create/decode/tampered/empty)
test_chat_response_service.py	Unitário	17	should_hide_sources, select_sources, format_sources_block
test_rag_service_unit.py	Unitário	23	Sanitize, dedup, history_str, process_docs, chunks, título

Rodar a suite completa com relatório de cobertura:

cd api
pytest

O pytest.ini já configura --cov=app --cov-report=term-missing --cov-fail-under=60. O relatório HTML fica em api/htmlcov/index.html.

Para rodar apenas os testes unitários (sem banco, sem fixtures de integração):

cd api
pytest tests/test_auth_utils.py tests/test_chat_response_service.py tests/test_rag_service_unit.py -v

Frontend

cd web
pnpm lint
pnpm build

Documentacao por Modulo

• Backend: api/README.md
• Frontend: web/README.md
• Operacao de ingestao: api/docs/ingest-instruction.md
• Análise de incidente: INCIDENT_ANALYSIS.md — falha silenciosa no pipeline de ingestão RAG (base vetorial desatualizada sem alertas), diagnóstico e resolução.

📚 Documentação da API

Desenvolvimento local:

• Swagger UI (interativo): http://localhost:8000/docs
• Documentação estática: api/docs/api-doc.md

Produção (Render):

• Swagger UI: https://allercheck-api.onrender.com/docs

Recursos Principais

Chat com RAG

• POST /chat: Chat em streaming com histórico.
• POST /evaluate/detailed: Análise detalhada com reescrita de query, reranking semântico e LLM provider.
• POST /evaluate/comparison: Compara LLM vs SLM (Ollama local) lado a lado com métricas de latência e custo.
• POST /evaluate/chunks: Retorna chunks recuperados pelo RAG sem gerar resposta.

Configuração de Providers

Altere REWRITE_PROVIDER e ANSWER_PROVIDER em .env:

• gemini: Gemini 2.5 Flash (padrão, recomendado)
• openai: GPT-4o-mini ou GPT-4o
• ollama: Modelos locais (Mistral, Qwen, etc.)

Troubleshooting

1. Erro Google authentication is not configured: Confirme GOOGLE_CLIENT_ID no .env e refaça docker compose up -d --build web api.

2. Erro de conexão com banco: Confirme DATABASE_URL e status do serviço db com docker compose ps.

3. Sem respostas RAG: Valide OPENAI_API_KEY, PINECONE_API_KEY, INDEX_NAME e os logs do ingest-worker com docker compose logs ingest-worker.

4. Ollama não responde: Verifique se está em http://localhost:11434 (local) ou http://ollama:11434 (Docker). Teste com curl http://localhost:11434/api/tags.

5. Variável de ambiente faltando (KeyError): Copie .env.example para .env e preencha todos os campos marcados como OBRIGATÓRIOS:

   REWRITE_TEMPERATURE=0.1
   ANSWER_TEMPERATURE=0.2
   EVALUATOR_TEMPERATURE=0
   BENCHMARK_TEMPERATURE=0.2
   

6. Inconsistência na base vetorial: Se copiou o projeto de outra máquina, remova os logs antigos:

   rm -rf api/logs/*.json api/logs/*.jsonl api/logs/*.txt
   docker compose down -v
   docker compose up -d --build