espiritismo-rag-system/README.md

Sistema RAG Espiritismo

<<<<<<< HEAD Sistema de consulta assistida por IA para livros de espiritismo em PDF.

Stack

• GPT4All + Llama 3.2 3B (CPU-only)
• LangChain para RAG
• Qdrant para vectores
• FastAPI + HTML/CSS/JS

Quick Start

1. Clone o repositório
2. Configure o .env
3. Baixe o modelo Llama 3.2 3B quantized
4. docker-compose up --build

Comandos

• docker-compose up: Start all services
• docker-compose run --rm web python backend/scripts/index_books.py: Indexar livros =======

Sistema de consulta assistida por IA para livros de espiritismo em PDF, com interface web rica e bot do Telegram.

🚀 Visão Geral

Este projeto implementa um Sistema RAG (Retrieval-Augmented Generation) completo para consultar e analisar livros de espiritismo usando inteligência artificial. O sistema permite:

• 🔍 Chat Inteligente: Pergunte sobre espiritismo e receba respostas baseadas nos livros
• 📄 Upload de PDFs: Adicione novos livros facilmente
• 📱 Bot Telegram: Receba conteúdo agendado no Telegram
• 🌐 Interface Web: Interface amigável e responsiva
• 🤖 IA Local: Modelos em CPU-only (Llama 3.2 3B)

📋 Stack Tecnológica

IA & Machine Learning

• GPT4All: Framework para modelos LLM local
• Llama 3.2 3B: Modelo quantizado em 4-bit (aprox. 2GB)
• LangChain: Framework para aplicações RAG
• Sentence Transformers: Geração de embeddings
• Qdrant: Banco de dados vetorial

Backend & API

• FastAPI: Framework web moderno e rápido
• Pydantic: Validação de dados
• Celery: Processamento assíncrono
• Redis: Broker para Celery

Frontend

• HTML5/CSS3: Estrutura e estilização
• Vanilla JavaScript: Interatividade

Deployment

• Docker: Containerização
• Docker Compose: Orquestração de serviços
• Gitea: Hospedagem do código

📋 Funcionalidades

1. Chat com IA

• Interface de chat intuitiva
• Respostas baseadas nos livros indexados
• Citações de fontes com referências

2. Upload de PDFs

• Upload de novos livros PDF
• Processamento automático de texto
• Indexação em Qdrant

3. Bot Telegram

• /start: Apresentação do sistema
• /help: Lista de comandos disponíveis
• /status: Verificar status do sistema
• /books: Listar livros disponíveis
• Comando de pergunta: Enviar perguntas diretamente ao bot

4. Agendamento de Mensagens

• Criar agendamentos via interface web
• Escolher data/hora específica
• Especificar livro ou "todos os livros"

5. Conteúdo Diário

• Geração automática de conteúdo diário
• Enviado às 8:00 todos os dias

📁 Estrutura do Projeto

espiritismo-rag-system/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI com todas as rotas
│   │   ├── models.py            # Pydantic models
│   │   ├── services/
│   │   │   ├── rag_service.py   # RAGService (Qdrant + LLM)
│   │   │   ├── pdf_processor.py # PDFProcessor
│   │   │   └── bot_service.py   # Telegram Bot
│   │   ├── utils/
│   │   │   ├── embeddings.py    # EmbeddingService
│   │   │   └── schedule_manager.py # CRUD de agendamentos
│   │   ├── templates/
│   │   │   └── index.html       # Interface web
│   │   └── tasks/
│   │       └── celery_tasks.py  # Celery tasks
│   ├── scripts/
│   │   └── index_books.py       # Script de indexação
│   ├── Dockerfile               # Container backend
│   └── requirements.txt         # Dependências Python
├── frontend/
│   └── static/
│       ├── css/style.css        # Estilos
│       └── js/script.js         # JavaScript funcional
├── docs/
│   └── superpowers/
│       ├── plans/
│       │   └── 2025-11-01-espiritismo-rag-system.md
│       └── specs/
│           └── 2025-11-01-espiritismo-rag-system-design.md
├── PDF/                         # Livros PDF (6 livros)
├── docker-compose.yml           # Orquestração de serviços
├── .env                         # Variáveis de ambiente
├── .env.example                 # Template de .env
├── BUILD.md                     # Instruções de build
├── README.md                    # Este arquivo
└── IMPLEMENTATION_COMPLETE.md   # Resumo da implementação

🔧 Pré-requisitos

• Docker e Docker Compose instalados
• ~5GB de espaço em disco
• 8GB de RAM (recomendado)
• CPU para inferência de modelo

📦 Instalação e Deploy

1. Clone o Repositório

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

2. Download do Modelo (Aprox. 2GB)

cd backend
mkdir -p models

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

# Ou use o GPT4All para baixar automaticamente

3. Configurar Variáveis de Ambiente

cp backend/.env.example .env

Edite o arquivo .env:

GPT4ALL_MODEL=models/llama-3.2-3b-instruct-q4_0.gguf
QDRANT_URL=http://localhost:6333
TELEGRAM_BOT_TOKEN=seu_token_aqui
TELEGRAM_CHAT_ID=seu_chat_id_aqui
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0
UPLOAD_DIR=/app/uploads
INDEX_DIR=/app/index

Para obter seu Telegram Bot Token:

1. Chat com @BotFather no Telegram
2. Envie /newbot e siga as instruções
3. Copie o token

Para obter seu Chat ID:

1. Crie um bot com @BotFather
2. Envie /start para o bot
3. Use uma ferramenta como curl "https://api.telegram.org/bot<token>/getUpdates"

4. Build e Start dos Serviços

# Build das imagens Docker
docker-compose build

# Start de todos os serviços
docker-compose up -d

# Verificar status
docker-compose ps

5. Indexar os Livros

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

Isso irá:

• Carregar os 6 livros PDF da pasta PDF/
• Extrair texto e gerar chunks
• Criar embeddings com Sentence Transformers
• Salvar em Qdrant

6. Acessar os Serviços

• Web Interface: http://localhost:8000
• Qdrant Dashboard: http://localhost:6333/dashboard
• Redis: localhost:6379

📖 Uso

Web Interface

1. Abra http://localhost:8000 no navegador
2. Digite uma pergunta sobre espiritismo
3. Receba resposta com fontes
4. Faça upload de novos PDFs
5. Crie agendamentos de mensagens

Telegram Bot

1. Inicie o bot com /start
2. Use /help para ver comandos
3. Use /status para ver status
4. Use /books para listar livros
5. Pergunte qualquer coisa para receber respostas

Agendamento de Mensagens

1. Acesse a interface web
2. Vá até "Agendar Mensagens"
3. Selecione data/hora
4. Escolha livro ou "Todos os livros"
5. Clique em "Adicionar Agendamento"

🔄 Agendamentos Automáticos

O sistema executa automaticamente:

• A cada hora: Envia mensagens agendadas
• Todo dia às 8:00: Gera conteúdo diário

🧪 Testando

Testar Chat

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Qual é o princípio fundamental do espiritismo?", "top_k": 3}'

Testar Lista de Livros

curl http://localhost:8000/api/books

Testar Upload de PDF

curl -X POST http://localhost:8000/api/upload \
  -F "file=@caminho/para/seu/livro.pdf"

📊 Monitoramento

Ver Logs dos Serviços

# Todos os serviços
docker-compose logs -f

# Web service
docker-compose logs -f web

# Celery worker
docker-compose logs -f celery

# Celery beat
docker-compose logs -f celery-beat

# Qdrant
docker-compose logs -f qdrant

Ver Status dos Containers

docker-compose ps

🛠️ Deploy em Produção

Requisitos para Produção

• Servidor dedicado (recomendado 8GB+ RAM)
• Docker instalado
• Modelo Llama 3.2 3B baixado
• Credenciais de Telegram configuradas

Deploy Padrão

# Build
docker-compose build

# Start
docker-compose up -d

# Indexar livros
docker-compose run --rm web python backend/scripts/index_books.py

Configuração de Ambiente de Produção

Configure .env para produção:

TELEGRAM_BOT_TOKEN=sua_token_producao
TELEGRAM_CHAT_ID=sua_chat_id
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

Escalabilidade

Para escalar, use:

• Proxy reverso (Nginx)
• Load balancer
• Mais instâncias do backend
• Cluster do Qdrant

🐛 Troubleshooting

Problemas de Build

# Limpar cache e rebuild
docker-compose build --no-cache

# Ver logs do build
docker-compose logs web

Qdrant Não Inicia

# Remover volume existente
docker volume rm espiritismo_qdrant_data

# Reiniciar
docker-compose up -d qdrant

Out of Memory

Reduza os workers:

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

Erros de Import

# Rebuild e clean
docker-compose down
docker-compose build --no-cache
docker-compose up -d

📈 Métricas

Performance Estimada

• Indexação de 6 livros: ~5-10 minutos (CPU)
• Tempo de resposta: ~2-5 segundos por pergunta
• Consumo de RAM: ~4GB (com modelo carregado)
• Espaço em disco: ~5GB total

Resources

• Llama 3.2 3B q4_0: ~2GB
• Embeddings (384 dims): ~1GB
• Qdrant index: ~1GB
• Livros PDF: ~1GB

📝 Licença

MIT License - Veja arquivo LICENSE para detalhes.

👥 Autores

Desenvolvido com ❤️ para a comunidade de espiritismo.

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se livre para:

• Reportar bugs
• Sugerir melhorias
• Enviar pull requests
• Adicionar novos livros

📄 Documentação Completa

Para documentação detalhada da implementação, veja:

• Design Document: docs/superpowers/specs/2025-11-01-espiritismo-rag-system-design.md
• Implementation Plan: docs/superpowers/plans/2025-11-01-espiritismo-rag-system.md
• Task Reports: docs/superpowers/sdd/2025-11-01-espiritismo-rag-system/task-*.md

🔗 Links Úteis

• FastAPI Documentation
• GPT4All Documentation
• LangChain Documentation
• Qdrant Documentation
• Llama 3.2 Model

---

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

50ae4db417