commit 89344763310cdbd9357868877344eeec36acf8ca Author: Luiz Gustavo Costa Date: Sun Nov 1 10:46:53 2026 -0300 feat: Adicionar documentação rica completa do Sistema RAG Espiritismo - Documentação visão geral e stack tecnológica - Instruções de instalação e deploy - Funcionalidades detalhadas - Estrutura do projeto - Guia de uso (Web, Telegram, Agendamento) - Comandos de teste e monitoramento - Troubleshooting e escalabilidade - Links úteis e referências Versão 1.0.0 - Production Ready diff --git a/README.md b/README.md new file mode 100644 index 0000000..a22bcb9 --- /dev/null +++ b/README.md @@ -0,0 +1,418 @@ +# Sistema RAG Espiritismo + +![Python](https://img.shields.io/badge/Python-3.11-blue.svg) +![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg) +![License](https://img.shields.io/badge/License-MIT-green.svg) + +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 + +```bash +git clone https://git.labexposed.com/lgcosta/espiritismo-rag-system.git +cd espiritismo-rag-system +``` + +### 2. Download do Modelo (Aprox. 2GB) + +```bash +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 + +```bash +cp backend/.env.example .env +``` + +Edite o arquivo `.env`: + +```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/getUpdates"` + +### 4. Build e Start dos Serviços + +```bash +# 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 + +```bash +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 + +```bash +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 + +```bash +curl http://localhost:8000/api/books +``` + +### Testar Upload de PDF + +```bash +curl -X POST http://localhost:8000/api/upload \ + -F "file=@caminho/para/seu/livro.pdf" +``` + +## 📊 Monitoramento + +### Ver Logs dos Serviços + +```bash +# 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 + +```bash +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 + +```bash +# 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: + +```env +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 + +```bash +# Limpar cache e rebuild +docker-compose build --no-cache + +# Ver logs do build +docker-compose logs web +``` + +### Qdrant Não Inicia + +```bash +# Remover volume existente +docker volume rm espiritismo_qdrant_data + +# Reiniciar +docker-compose up -d qdrant +``` + +### Out of Memory + +Reduza os workers: +```bash +# Edit docker-compose.yml +celery: + command: celery -A app.tasks.celery_tasks worker --loglevel=info --concurrency=2 +``` + +### Erros de Import + +```bash +# 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](https://fastapi.tiangolo.com/) +- [GPT4All Documentation](https://gpt4all.io/) +- [LangChain Documentation](https://python.langchain.com/) +- [Qdrant Documentation](https://qdrant.tech/documentation/) +- [Llama 3.2 Model](https://huggingface.co/meta-llama/Llama-3.2) + +--- + +**Versão**: 1.0.0 +**Status**: Production Ready ✅ +**Última Atualização**: 2026-11-01