lgcosta/espiritismo-rag-system
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implementar sistema RAG Espiritismo completo

Browse Source 
- Stack: GPT4All + Llama 3.2 3B, LangChain, Qdrant, FastAPI, Docker
- 11 tarefas implementadas com 100% de conclusão
- Funcionalidades: chat com IA, upload PDF, bot Telegram, agendamento
- 6 livros PDF indexados (A Gênese, Livro dos Espíritos, etc.)
- Documentação rica: README, BUILD, task reports, design specs
- Deploy com Docker Compose
- Production ready

Tech stack:
- AI: GPT4All 2.4.6, Llama 3.2 3B q4_0
- Backend: FastAPI 0.115.0, Celery 5.4.0, Redis 5.2.0
- RAG: LangChain 0.3.7, Qdrant 1.11.1
- Frontend: HTML5/CSS3/Vanilla JS
- Deploy: Docker Compose

Acceptance Criteria:
✅ CPU-only, <8GB RAM, ~5GB storage
✅ Suporta upload de PDFs
✅ Interface web rica e responsiva
✅ Bot Telegram funcional
✅ Agendamento de mensagens
✅ Código limpo e documentado
✅ Deploy via Docker

Status: PRODUCTION READY
Version: 1.0.0
Date: 2026-11-01
This commit is contained in:
lgcosta committed 2026-11-01 10:56:17 -03:00
commit b9c0c66d21
56 files changed
+5793
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/superpowers/specs/2025-11-01-espiritismo-rag-system-design.md
+176
View File
@@ -0,0 +1,176 @@
# Sistema de Consulta RAG para Livros de Espiritismo
## Intent and the Why
Desenvolver um sistema de pesquisa assistida por IA (RAG) para consulta em linguagem natural aos livros de espiritismo em PDF, com interface web rica e integração com Telegram para envio de conteúdo diário. O sistema deve ser leve, executar em CPU sem GPU, e ser facilmente deployável em servidor dedicado via Docker.
## Goals, Non-goals, Anti-goals
### Goals (Objetivos)
- Processar 6 livros de espiritismo em PDF (A Gênese, Livro dos Espíritos, Livro dos Médiuns, O Céu e o Inferno, O Evangelho Segundo o Espiritismo, O que é o Espiritismo)
- Permitir consultas em linguagem natural via interface web
- Interface web rica, amigável e responsiva
- Agendar mensagens de conteúdo dos livros via bot Telegram
- Suportar agregação de novos livros PDF no futuro
- Executar totalmente em CPU sem GPU
- Deploy simples via Docker em servidor dedicado
- Armazenamento vetorial em Qdrant
- Rastreamento de citações e fontes dos livros
### Non-goals (Não-objetivos)
- Sincronização com outras fontes externas
- Multi-tenancy (usuários múltiplos)
- Tradução automática para outros idiomas
- Processamento em tempo real de documentos via API
### Anti-goals (Anti-objetivos - comportamentos indesejados)
- Sistema pesado, exigindo GPU
- Interface web complexa ou difícil de usar
- Agendamento sem controle visual
- Perda de contexto ou citações sem referência
- Configuração complexa para deploy
## Constraints (Restrições)
- CPU-only, sem GPU
- Máximo 8GB RAM (servidor dedicado típico)
- Armazenamento: ~500MB para modelo (quantizado), ~2GB para vetores (6 livros)
- Armazenamento vetorial: Qdrant em Docker
- API Web: FastAPI + React (ou HTML/CSS/JS simples)
- Bot Telegram: Python pyTelegramBotAPI
- Agendamento: Celery + Redis ou Cron simples
## Approaches (Abordagens Consideradas)
### Abordagem A: Stack completa customizada (Llama3 + LangChain + Qdrant)
- Usar Llama3 8B quantized via GPT4All
- LangChain para pipeline de RAG
- Qdrant para vectores
- FastAPI para API web
- React para frontend
- pyTelegramBotAPI para bot Telegram
- Cron jobs para agendamento
- Docker compose para orquestração
**Vantagens**: Mais controle, totalmente self-contained, pode adicionar recursos facilmente
**Desvantagens**: Maior complexidade de configuração, mais manutenção
### Abordagem B: Stack minimalista (GPT4All + LangChain + Qdrant) - SELECIONADA
- Usar GPT4All + Llama 3.2 3B (ou mistral 7B)
- LangChain para pipeline de RAG
- Qdrant para vectores
- FastAPI para API web
- Interface web simples mas rica (HTML/CSS/JS)
- pyTelegramBotAPI para bot Telegram
- Celery + Redis para agendamento
- Docker compose para orquestração
**Vantagens**: Menor complexidade, mais simples de manter, código legível
**Desvantagens**: Menos flexibilidade para extensões complexas
### Abordagem C: Template open-source (chat-with-your-pdf + Telegram bot)
- Usar template pronto chat-with-your-pdf
- Integrar com bot Telegram existente
- Docker para containerização
**Vantagens**: Já funcional, comunidade, documentação
**Desvantagens**: Menos customization, dependência de terceiros
**Por que a Abordagem B?**
- Balancea controle e complexidade
- Permite fácil expansão futura
- Código legível e manutenível
- Comunitários ativos (GPT4All, LangChain, Qdrant)
- Deploys simples via Docker
- Tamanho moderado (aprox. 5GB total)
## Architecture Components (Componentes da Arquitetura)
### Backend
- **FastAPI**: API REST para interface web
- **LangChain**: Orquestração do pipeline RAG
- **GPT4All**: Modelo de linguagem em CPU
- **Qdrant**: Banco vetorial para embeddings
- **PDF Loader**: Parse de PDFs com LangChain
- **Embeddings**: SentenceTransformers ou model do GPT4All
### Frontend
- **HTML/CSS/JS**: Interface web simples e responsiva
- **Chat interface**: Input de perguntas e display de respostas com citações
- **Upload de PDF**: Interface para adicionar novos livros
- **Configuração de horários**: Formulário para agendar mensagens no Telegram
### Telegram Bot
- **pyTelegramBotAPI**: Interface para Telegram
- **Mensagens agendadas**: Celery tasks com cron expressions
- **Controle via bot**: Comandos para configurar horários e visualizar conteúdo
### Orquestração
- **Docker Compose**: Containerização de todos os serviços
- **Celery**: Processamento assíncrono de tarefas (agendamentos)
- **Redis**: Cache e broker para Celery
- **Nginx**: Proxy reverso (opcional)
## Data Flow (Fluxo de Dados)
1. **Indexação inicial**:
- PDFs são processados e divididos em chunks
- Chunks são convertidos em embeddings
- Embeddings são armazenados no Qdrant
2. **Consulta web**:
- Usuário faz pergunta via interface web
- Pergunta é convertida em embedding
- Busca em Qdrant retorna chunks relevantes
- Chunks são passados ao modelo LLM
- Resposta é gerada com citações
- Resposta é exibida na interface
3. **Mensagem agendada**:
- Celery schedule executa task no horário agendado
- Task gera conteúdo aleatório dos livros
- Bot Telegram envia mensagem
## Future Extensions (Extensões Futuras)
- Upload de novos PDFs via interface web
- Múltiplos usuários com autenticação
- Análise estatística de livros
- Exportação de conteúdo
- Configuração de horários via interface web
- Histórico de consultas
## Development Phases (Fases de Desenvolvimento)
1. Setup Docker e componentes base (Qdrant, Redis)
2. Indexação dos 6 livros existentes
3. Desenvolvimento da API web com chat
4. Desenvolvimento da interface web
5. Integração com Telegram bot
6. Implementação de agendamento de mensagens
7. Testes e otimização
8. Deploy em produção
## Implementation Details (Detalhes de Implementação)
### Docker Services
- `web`: FastAPI backend + HTML frontend
- `vectorstore`: Qdrant
- `redis`: Redis para Celery
- `worker`: Celery worker para tarefas assíncronas
- `nginx`: Proxy reverso (opcional)
### Environment Variables
- `GPT4ALL_MODEL`: caminho do modelo (llama-3.2-3b-instruct-q4_0.gguf)
- `QDRANT_URL`: URL do Qdrant
- `TELEGRAM_BOT_TOKEN`: token do bot
- `TELEGRAM_CHAT_ID`: ID do chat para envio de mensagens
- `CELERY_BROKER_URL`: URL do Redis
- `CELERY_RESULT_BACKEND`: URL do Redis
## Size of Work (Tamanho do Trabalho)
**Projeto** - design completo com todos os componentes, arquitetura e implementação.
docs/superpowers/specs/2025-11-01-espiritismo-rag-system-plan.md
+223
View File
@@ -0,0 +1,223 @@
# 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
```python
# 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
```env
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