espiritismo-rag-system/BUILD.md

# Build e Deployment Instructions

![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)
![Python](https://img.shields.io/badge/Python-3.11-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)

Instruções completas para build, deploy e uso do Sistema RAG Espiritismo.

## 📋 Conteúdo

- [Pré-requisitos](#pré-requisitos)
- [Download do Modelo](#download-do-modelo)
- [Configuração de Ambiente](#configuração-de-ambiente)
- [Build do Projeto](#build-do-projeto)
- [Deploy com Docker Compose](#deploy-com-docker-compose)
- [Indexação dos Livros](#indexação-dos-livros)
- [Uso da Aplicação](#uso-da-aplicação)
- [Monitoramento](#monitoramento)
- [Troubleshooting](#troubleshooting)
- [Segurança](#segurança)
- [Escalabilidade](#escalabilidade)

## 🔧 Pré-requisitos

### Hardware

- **CPU**: 4+ cores (recomendado)
- **RAM**: 8GB mínima (12GB recomendado)
- **Disco**: 5GB disponíveis
- **Rede**: Conexão estável para downloads

### Software

- **Docker**: Versão 20.10+ (https://docs.docker.com/get-docker/)
- **Docker Compose**: Versão 2.0+ (https://docs.docker.com/compose/install/)
- **Git**: Versão 2.0+ (https://git-scm.com/downloads)
- **Terminal**: bash/zsh compatível

### Acesso à Internet

- Para download do modelo (~2GB)
- Para clones do repositório
- Para pull de imagens Docker

## 📥 Download do Modelo

### Opção 1: Manual Download

```bash
cd backend
mkdir -p models

# Baixe o modelo Llama 3.2 3B quantizado (4-bit)
wget https://huggingface.co/MaziyarPanahi/Llama-3.2-3B-Instruct-GGUF/resolve/main/llama-3.2-3b-instruct-q4_0.gguf

# Valide o tamanho (deve ser ~2GB)
ls -lh models/llama-3.2-3b-instruct-q4_0.gguf

# Mova para o diretório correto
mv llama-3.2-3b-instruct-q4_0.gguf models/
```

### Opção 2: GPT4All Auto-Download

```bash
cd backend

# Inicie o serviço web primeiro
docker-compose run --rm web

# Na interface web, o GPT4All vai baixar o modelo automaticamente
# ou use: curl -O https://gpt4all.io/models/Llama-3-2-3B-Instruct-GGUF-Q4_0.gguf
```

### Opção 3: Script Automático

```bash
#!/bin/bash
# download_model.sh

cd backend
mkdir -p models

MODEL_URL="https://huggingface.co/MaziyarPanahi/Llama-3.2-3B-Instruct-GGUF/resolve/main/llama-3.2-3b-instruct-q4_0.gguf"

if [ ! -f "models/llama-3.2-3b-instruct-q4_0.gguf" ]; then
    echo "Baixando modelo Llama 3.2 3B..."
    wget -O models/llama-3.2-3b-instruct-q4_0.gguf "$MODEL_URL"
    echo "Download concluído!"
else
    echo "Modelo já existe!"
fi
```

### Validação do Download

```bash
# Verifique o tamanho
ls -lh backend/models/llama-3.2-3b-instruct-q4_0.gguf

# Esperado: ~2.0 GB

# Verifique o hash (opcional)
sha256sum backend/models/llama-3.2-3b-instruct-q4_0.gguf
```

## ⚙️ Configuração de Ambiente

### 1. Clone o Repositório

```bash
git clone https://git.labexposed.com/lgcosta/espiritismo-rag-system.git
cd espiritismo-rag-system
```

### 2. Copie o Template de Variáveis de Ambiente

```bash
cp backend/.env.example .env
```

### 3. Configure as Variáveis

Edite o arquivo `.env` com suas configurações:

```env
# === Configurações do Modelo ===
GPT4ALL_MODEL=models/llama-3.2-3b-instruct-q4_0.gguf
MODEL_PATH=/app/models/llama-3.2-3b-instruct-q4_0.gguf

# === Configurações do Qdrant ===
QDRANT_URL=http://qdrant:6333
QDRANT_API_KEY=  # Opcional, deixe vazio se não usar autenticação

# === Configurações do Telegram Bot ===
TELEGRAM_BOT_TOKEN=sua_token_aqui
TELEGRAM_CHAT_ID=sua_chat_id_aqui

# === Configurações do Celery ===
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://6379/0

# === Caminhos ===
UPLOAD_DIR=/app/uploads
INDEX_DIR=/app/index
SCHEDULES_PATH=/app/schedules.json

# === Configurações de Debug ===
DEBUG=false
LOG_LEVEL=INFO
```

### 4. Como Obter Telegram Bot Token

#### Criar o Bot

1. Abra o Telegram e procure por @BotFather
2. Envie `/newbot`
3. Siga as instruções:
   - Dê um nome para o bot (ex: "EspiritismoBot")
   - Dê um username único (ex: "espiritismo_bot")
4. Copie o token fornecido

#### Obter seu Chat ID

```bash
# Método 1: Usando curl
curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getUpdates"

# Procure pela chave "id" no resultado
# Exemplo: "id": 123456789

# Método 2: Usando uma URL no navegador
https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getUpdates
```

### 5. Validar Configuração

```bash
# Verifique se .env existe e não está vazio
if [ -s .env ]; then
    echo "✅ Configuração de ambiente válida"
else
    echo "❌ .env está vazio ou não existe"
fi
```

## 🏗️ Build do Projeto

### 1. Limpar Cache Anterior (Opcional)

```bash
# Remove imagens existentes
docker-compose down
docker system prune -a -f

# Remove volumes (apenas se necessário)
docker volume rm espiritismo_qdrant_data 2>/dev/null || true
docker volume rm espiritismo_redis_data 2>/dev/null || true
```

### 2. Build das Imagens Docker

```bash
# Build básico
docker-compose build

# Build completo com cache
docker-compose build --no-cache

# Build com progresso detalhado
docker-compose build --progress=plain
```

### 3. Verificar Imagens Buildadas

```bash
# Listar imagens
docker images | grep espiritismo

# Verificar tamanho
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" | grep espiritismo
```

**Esperado:**
- `lgcosta/espiritismo-web:latest` (~1.2GB)
- `lgcosta/espiritismo-celery:latest` (~1.2GB)

## 🚀 Deploy com Docker Compose

### 1. Iniciar Todos os Serviços

```bash
# Start em background
docker-compose up -d

# Start com logs
docker-compose up
```

### 2. Verificar Status dos Serviços

```bash
# Lista todos os containers
docker-compose ps

# Status específico
docker-compose ps qdrant
docker-compose ps redis
docker-compose ps web
```

**Esperado:**
```
NAME                       STATUS
espiritismo-qdrant         Up 10 seconds
espiritismo-redis          Up 10 seconds
espiritismo-web            Up 10 seconds
espiritismo-celery         Up 10 seconds
espiritismo-celery-beat    Up 10 seconds
```

### 3. Ver Logs

```bash
# Logs de todos os serviços
docker-compose logs -f

# Logs do web service
docker-compose logs -f web

# Logs do celery
docker-compose logs -f celery

# Logs do celery beat
docker-compose logs -f celery-beat

# Logs do qdrant
docker-compose logs -f qdrant

# Últimas 100 linhas
docker-compose logs --tail=100
```

### 4. Acessar os Serviços

- **Web Interface**: http://localhost:8000
- **Qdrant Dashboard**: http://localhost:6333/dashboard
- **API Documentation**: http://localhost:8000/docs

## 📚 Indexação dos Livros

### 1. Listar Livros Disponíveis

```bash
# Lista arquivos na pasta PDF
ls -lh PDF/

# Deve mostrar:
# A_Genese-Guillon.pdf
# Livro_dos_Espiritos-Guillon.pdf
# Livro_dos_Mediuns-Guillon.pdf
# O_Ceu_e_o_Inferno-Manuel_Quintao.pdf
# O_Evangelho_Segundo_o_Espiritismo-Guillon.pdf
# O_que_e_o_Espiritismo.pdf
```

### 2. Executar Script de Indexação

```bash
# Método 1: Via container
docker-compose run --rm web python backend/scripts/index_books.py

# Método 2: Com limite de logs
docker-compose run --rm web python backend/scripts/index_books.py 2>&1 | tee index.log
```

### 3. Monitorar Progresso

```bash
# Processando logs
docker-compose logs -f web

# Esperado:
# Found 6 books
# Processing: A_Genese-Guillon.pdf
# Saved 120 chunks to /app/index/A_Genese-Guillon.json
# Processing: Livro_dos_Espiritos-Guillon.pdf
# ...
# Indexing complete!
```

### 4. Verificar Indexação

```bash
# Lista de chunks indexados
ls -lh backend/index/

# Conteúdo de um chunk JSON (exemplo)
cat backend/index/A_Genese-Guillon.json | head -20

# Verificar em Qdrant
curl http://localhost:6333/collections/espiritismo_books
```

### 5. Reindexar (Se Necessário)

```bash
# Limpar indexação anterior
rm -rf backend/index/*
rm backend/schedules.json

# Reindexar
docker-compose run --rm web python backend/scripts/index_books.py
```

## 🎮 Uso da Aplicação

### Web Interface

1. **Acesse a interface:**
   ```
   http://localhost:8000
   ```

2. **Teste o Chat:**
   - Digite: "Qual é o princípio fundamental do espiritismo?"
   - Clique em "Enviar"
   - Receba resposta com fontes

3. **Upload de PDF:**
   - Clique em "Upload PDF"
   - Selecione arquivo PDF
   - Clique em "Upload PDF"
   - Confirme mensagem de sucesso

4. **Agendamento:**
   - Vá até "Agendar Mensagens"
   - Selecione data/hora
   - Escolha livro ou "Todos os livros"
   - Clique em "Adicionar Agendamento"
   - Confirme que apareceu na lista

### Bot Telegram

#### Configuração

```bash
# Verifique se bot está ativo
docker-compose logs celery | grep -i "polling\|started"

# Deve ver:
# Starting Telegram bot polling...
```

#### Comandos Disponíveis

1. **/start** - Apresentação
   ```
   /start
   
   📚 Sistema RAG Espiritismo

   Comandos disponíveis:
   /start - Iniciar
   /help - Ajuda
   /status - Ver status
   /books - Listar livros
   ```

2. **/help** - Lista de comandos
   ```
   /help

   📚 Sistema RAG Espiritismo

   Comandos disponíveis:
   /start - Iniciar
   /help - Ajuda
   /status - Ver status
   /books - Listar livros
   ```

3. **/status** - Status do sistema
   ```
   /status

   📚 Status do Sistema RAG Espiritismo

   Bot: Ativo
   Chat ID: 123456789

   Direcione uma pergunta sobre espiritismo para eu responder!
   ```

4. **/books** - Lista de livros
   ```
   /books

   📚 Livros disponíveis:

   • A Gênese (Allan Kardec)
   • Livro dos Espíritos (Allan Kardec)
   • Livro dos Médiums (Allan Kardec)
   • O Céu e o Inferno (Manuel Quintão)
   • O Evangelho Segundo o Espiritismo (Allan Kardec)
   • O Que é o Espiritismo (Allan Kardec)
   ```

5. **Pergunta** - Responder perguntas
   ```
   Qual é a doutrina da reencarnação?
   
   🔍 Processando sua pergunta...
   
   ✅ Resposta:
   
   A reencarnação é um dos princípios fundamentais do espiritismo...
   
   📚 Fontes:
   • A Gênese (chunk 45)
   • Livro dos Espíritos (chunk 78)
   • ...
   ```

### Agendamento de Mensagens

1. **Criar Agendamento**
   ```
   Data/Hora: 2026-11-02T10:00
   Livro: Livro dos Espíritos
   ```
   - Mensagem enviada automaticamente às 10:00
   - Contém resumo do livro escolhido

2. **Agendar para Todos os Livros**
   ```
   Data/Hora: 2026-11-02T14:00
   Livro: Todos os livros
   ```
   - Mensagem enviada às 14:00 com conteúdo de todos os livros

3. **Gerenciar Agendamentos**
   - Ver lista de agendamentos na web
   - Editar data/hora
   - Excluir agendamentos
   - Status de execução

## 📊 Monitoramento

### Métricas do Sistema

```bash
# CPU Usage
docker stats

# Memory Usage
docker stats --no-stream

# Container Status
docker-compose ps -a
```

### Logs por Serviço

```bash
# Logs web (últimos 50 linhas)
docker-compose logs --tail=50 web

# Logs celery (últimos 50 linhas)
docker-compose logs --tail=50 celery

# Logs celery beat (últimos 50 linhas)
docker-compose logs --tail=50 celery-beat

# Buscar logs específicos
docker-compose logs | grep "ERROR"
docker-compose logs | grep "WARNING"
docker-compose logs | grep "INFO" | grep "index"
```

### Health Checks

```bash
# Web API health
curl http://localhost:8000/docs

# Qdrant health
curl http://localhost:6333/collections/espiritismo_books

# Redis ping
docker-compose exec redis redis-cli ping
# Resposta: PONG
```

## 🐛 Troubleshooting

### Problemas Comuns

#### 1. Container não inicia

```bash
# Ver logs
docker-compose logs web

# Possível solução:
# Limpar e rebuild
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

#### 2. Out of Memory

```bash
# Ver uso de memória
docker stats

# Reduzir workers
# Edite docker-compose.yml
celery:
  command: celery -A app.tasks.celery_tasks worker --loglevel=info --concurrency=2

# Restart
docker-compose restart celery
```

#### 3. Qdrant não conecta

```bash
# Verificar status do Qdrant
docker-compose ps qdrant

# Ver logs
docker-compose logs qdrant

# Reiniciar
docker-compose restart qdrant
```

#### 4. Redis não conecta

```bash
# Verificar status do Redis
docker-compose ps redis

# Ver logs
docker-compose logs redis

# Reiniciar
docker-compose restart redis
```

#### 5. Erro no Model Loading

```bash
# Verificar se modelo existe
ls -lh backend/models/

# Baixar novamente
cd backend
wget https://huggingface.co/MaziyarPanahi/Llama-3.2-3B-Instruct-GGUF/resolve/main/llama-3.2-3b-instruct-q4_0.gguf

# Reiniciar containers
docker-compose down
docker-compose up -d
```

#### 6. Indexação falha

```bash
# Verificar arquivos PDF
ls -lh PDF/

# Verificar permissões
chmod -R 755 PDF/

# Reindexar
docker-compose run --rm web python backend/scripts/index_books.py 2>&1 | tee reindex.log
```

### Comandos de Diagnóstico

```bash
# Lista todos os containers
docker ps -a

# Ver detalhes de um container
docker inspect espiritismo-web

# Ver redes
docker network ls
docker network inspect espiritismo_default

# Ver volumes
docker volume ls
docker volume inspect espiritismo_qdrant_data
docker volume inspect espiritismo_redis_data
```

## 🔒 Segurança

### Hardening do Sistema

1. **Usar Variáveis de Ambiente Seguras**
   ```bash
   # Sempre use .env local para credenciais
   cp .env.example .env
   chmod 600 .env  # Apenas dono pode ler
   ```

2. **Não Expor Portas Externas**
   ```yaml
   # docker-compose.yml
   web:
     ports:
       - "127.0.0.1:8000:8000"  # Apenas local
   ```

3. **Proteger Qdrant (se necessário)**
   ```yaml
   qdrant:
     environment:
       - QDRANT_API_KEY=your_secret_key
   ```

4. **Atualizar Dependências Regularmente**
   ```bash
   # Verificar vulnerabilidades
   docker-compose exec web pip list --outdated
   ```

### Backups

```bash
# Backup de schedules
cp backend/schedules.json backend/schedules.json.backup

# Backup de index
tar -czf index_backup.tar.gz backend/index/

# Backup de uploads
tar -czf uploads_backup.tar.gz PDF/
```

## 📈 Escalabilidade

### Escalar para Múltiplas Instâncias

```yaml
# docker-compose.yml
web:
  deploy:
    replicas: 3
    resources:
      limits:
        cpus: '2'
        memory: 4G
```

### Load Balancing

```bash
# Usar Nginx como proxy
server {
    listen 80;
    server_name seu-dominio.com;

    location / {
        proxy_pass http://web:8000;
        proxy_set_header Host $host;
    }
}
```

### Cluster do Qdrant

```yaml
# Qdrant cluster
qdrant:
  command: >
    qdrant
    --host 0.0.0.0
    --port 6333
    --storage_path /qdrant/storage
    --disk_enabled
```

## 📝 Checklist de Deploy

### Pré-deploy Checklist

- [ ] Docker e Docker Compose instalados
- [ ] Modelo Llama 3.2 3B baixado
- [ ] Token do Telegram configurado
- [ ] Chat ID do Telegram configurado
- [ ] .env criado e configurado
- [ ] Repositório clonado
- [ ] Código versionado

### Deploy Checklist

- [ ] Docker images buildadas
- [ ] Todos os containers iniciados
- [ ] Container status "Up"
- [ ] Logs sem erros críticos
- [ ] Web API acessível em http://localhost:8000
- [ ] Qdrant acessível em http://localhost:6333/dashboard
- [ ] Indexação dos livros concluída
- [ ] Teste de chat realizado
- [ ] Teste do bot no Telegram realizado
- [ ] Agendamentos criados e testados

### Pós-deploy Checklist

- [ ] Monitoramento configurado
- [ ] Backups automáticos configurados
- [ ] Logs em produção configurados
- [ ] Alertas configurados
- [ ] Documentação atualizada
- [ ] Equipe treinada

## 🎯 Performance Tuning

### Otimizações Recomendadas

1. **Aumentar chunk_size** (em backend/services/pdf_processor.py):
   ```python
   self.text_splitter = RecursiveCharacterTextSplitter(
       chunk_size=1000,  # De 500 para 1000
       chunk_overlap=100,  # De 50 para 100
       length_function=len,
   )
   ```

2. **Aumentar top_k** (em frontend/static/js/script.js):
   ```javascript
   const result = await fetch(`${API_BASE}/chat`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ message, top_k: 5 }),  // De 3 para 5
   });
   ```

3. **Aumentar workers do Celery** (em docker-compose.yml):
   ```yaml
   celery:
     command: celery -A app.tasks.celery_tasks worker --loglevel=info --concurrency=4
   ```

### Monitoramento de Performance

```bash
# Métricas em tempo real
docker stats --no-stream

# CPU e memória por container
docker stats espiritismo-web

# Verificar se há gargalos
docker-compose logs | grep "slow\|timeout"
```

## 📞 Suporte

### Recursos

- [GitHub Issues](https://git.labexposed.com/lgcosta/espiritismo-rag-system/issues)
- [Documentação](README.md)
- [BUILD.md](BUILD.md)
- [Design Specs](docs/superpowers/specs/2025-11-01-espiritismo-rag-system-design.md)

### Canais de Comunicação

- Telegram: @seu_bot
- Email: suporte@exemplo.com
- Issues: https://git.labexposed.com/lgcosta/espiritismo-rag-system/issues

---

**Versão**: 1.0.0  
**Última Atualização**: 2026-11-01  
**Status**: Production Ready ✅