espiritismo-rag-system/docs/superpowers/specs/2025-11-01-espiritismo-rag-system-plan.md

Plano de Implementação - Sistema RAG Espiritismo

Fase 1: Setup Inicial e Componentes Base

1.1 Estrutura do Projeto

espiritismo-rag/
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── models/
│   │   ├── services/
│   │   ├── utils/
│   │   └── templates/
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   └── static/
├── docker-compose.yml
├── .env.example
└── README.md

1.2 Docker Compose

• Serviço qdrant: Qdrant em Docker
• Serviço redis: Redis em Docker
• Serviço web: FastAPI com frontend
• Serviço celery: Celery worker

1.3 Configuração do Qdrant

• Coleção: espiritismo_books
• Dimensão: 384 (sentence-transformers)
• Métrica: cosine similarity

Fase 2: Indexação dos Livros

2.1 Setup do Pipeline RAG

• Instalação de GPT4All
• Configuração do LangChain
• Configuração do PDF Loader

2.2 Processamento dos 6 Livros

• Leitura de PDFs da pasta PDF/
• Divisão em chunks de 500 tokens
• Geração de embeddings
• Inserção no Qdrant

2.3 Script de Indexação

• Script Python: backend/scripts/index_books.py
• Opções: re-indexação incremental
• Validação: verificar chunks e embeddings

Fase 3: API Web com Chat

3.1 FastAPI Endpoints

• POST /api/chat: Consulta ao sistema RAG
• GET /api/books: Lista de livros indexados
• GET /api/chunks/{book_id}: Ver chunks de um livro
• POST /api/upload: Upload de novo PDF
• GET /api/schedules: Listar agendamentos
• POST /api/schedules: Criar novo agendamento
• DELETE /api/schedules/{id}: Remover agendamento

3.2 Estrutura do Backend

# backend/app/main.py
app = FastAPI()
app.include_router(router_chat)
app.include_router(router_books)
app.include_router(router_upload)
app.include_router(router_schedules)

3.3 Configuração do Model

• Usar Llama 3.2 3B quantized via GPT4All
• Prompt template específico para espiritismo
• System prompt com instruções

Fase 4: Interface Web

4.1 Página Principal (index.html)

• Chat interface
• Seção de upload de PDFs
• Seção de configuração de horários
• Exibição de informações dos livros

4.2 Estilos (style.css)

• Design moderno e limpo
• Responsivo para mobile
• Tema claro/escuro
• Animações suaves

4.3 JavaScript (script.js)

• Comunicação com API
• Gestão de chat
• Upload de arquivos
• Manipulação de horários
• Feedback visual

Fase 5: Integração com Telegram Bot

5.1 Setup do Bot

• Instalação de pyTelegramBotAPI
• Configuração do bot com token
• Configuração do chat ID

5.2 Comandos do Bot

• /start: Mensagem de boas-vindas
• /help: Informações sobre comandos
• /list: Listar livros disponíveis
• /schedule: Configurar horário para mensagem
• /schedule list: Listar agendamentos
• /schedule remove <id>: Remover agendamento
• /content: Enviar conteúdo atual (sem agendamento)

5.3 Task do Celery

• Task: send_scheduled_message
• Variável aleatória de livros
• Mensagem formataada
• Timestamp da mensagem

Fase 6: Agendamento de Mensagens

6.1 Sistema de Agendamento

• Interface web para criar horários
• Campos: hora, livro (ou todos), tipo de conteúdo
• Persistence de agendamentos em arquivo JSON

6.2 Celery Beats

• Configuração do scheduler
• Execução diária das tarefas
• Log de execução

6.3 Comando do Bot

• /schedule <horário> <livro?>: Agendar mensagem
• Exemplo: /schedule 08:00 ou /schedule 08:00 Livro dos Espíritos

Fase 7: Testes e Otimização

7.1 Testes Unitários

• Testes do pipeline RAG
• Testes das APIs
• Testes do bot

7.2 Testes de Integração

• Testes de end-to-end
• Testes de indexação
• Testes de agendamento

7.3 Otimizações

• Cache de respostas
• Query optimization no Qdrant
• Pool de conexões Redis

Fase 8: Deploy

8.1 Docker Build

• Dockerfile para backend
• Dockerfile para frontend
• Docker Compose para orquestração

8.2 Deploy em Servidor

• Build da imagem
• Execução do docker-compose
• Configuração do Nginx (opcional)
• Configuração de certificado SSL (opcional)

8.3 Monitoramento

• Logs do Celery
• Logs da aplicação
• Monitoramento do Qdrant

Detalhes Técnicos

Requisitos Python

fastapi==0.104.1
uvicorn==0.24.0
pydantic==2.5.0
gpt4all==2.2.7
langchain==0.1.0
langchain-community==0.0.10
langchain-experimental==0.0.52
sentence-transformers==2.2.2
pytelegrambotapi==4.15.1
celery==5.3.4
redis==5.0.1
python-multipart==0.0.6
python-dotenv==1.0.0

Variáveis de Ambiente

GPT4ALL_MODEL=llama-3.2-3b-instruct-q4_0.gguf
QDRANT_URL=http://qdrant:6333
QDRANT_API_KEY=
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=123456789
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0
UPLOAD_DIR=/app/uploads
INDEX_DIR=/app/index

Frontend Endpoints

• POST /api/chat: Enviar pergunta
• POST /api/upload: Upload PDF
• GET /api/books: Listar livros
• GET /api/schedules: Listar agendamentos
• POST /api/schedules: Criar agendamento

Timeline Estimado

• Fase 1: 2-3 horas
• Fase 2: 3-4 horas
• Fase 3: 4-5 horas
• Fase 4: 3-4 horas
• Fase 5: 2-3 horas
• Fase 6: 2-3 horas
• Fase 7: 3-4 horas
• Fase 8: 2-3 horas

Total estimado: 21-29 horas de desenvolvimento