# 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
└── LICENSE                      # MIT License
```

## 🔧 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 -O llama-3.2-3b-instruct-q4_0.gguf "https://us.aws.cdn.hf.co/xet-bridge-us/6718a700b21019fade8d68ac/b472da725da9aaf0e050c885680a67f61fceb097eb4277b0cc1e0b94e3559345?user_id=public&xip=4ii5zzvItH8&X-Xet-Cas-Uid=public&response-content-disposition=attachment%3B+filename*%3DUTF-8%27%27llama-3.2-3b-instruct-q4_0.gguf%3B+filename%3D%22llama-3.2-3b-instruct-q4_0.gguf%22%3B&Expires=1793546619&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly91cy5hd3MuY2RuLmhmLmNvL3hldC1icmlkZ2UtdXMvNjcxOGE3MDBiMjEwMTlmYWRlOGQ2OGFjL2I0NzJkYTcyNWRhOWFhZjBlMDUwYzg4NTY4MGE2N2Y2MWZjZWIwOTdlYjQyNzdiMGNjMWUwYjk0ZTM1NTkzNDVcXD91c2VyX2lkPXB1YmxpYyZ4aXA9NGlpNXp6dkl0SDgmWC1YZXQtQ2FzLVVpZD1wdWJsaWMmcmVzcG9uc2UtY29udGVudC1kaXNwb3NpdGlvbj1hdHRhY2htZW50JTNCK2ZpbGVuYW1lJTJBJTNEVVRGLTglMjclMjdsbGFtYS0zLjItM2ItaW5zdHJ1Y3QtcTRfMC5nZ3VmJTNCK2ZpbGVuYW1lJTNEJTIybGxhbWEtMy4yLTNiLWluc3RydWN0LXE0XzAuZ2d1ZiUyMiUzQiIsIkNvbmRpdGlvbiI6eyJEYXRlTGVzc1RoYW4iOnsiRXBvY2hUaW1lIjoxNzkzNTQ2NjE5fX19XX0_&Signature=MEUCIBdL2cMsOqav%7EbG9Q2mearSLUBdBtfCA3sOBE5GdbXUnAiEA7xWOea%7ETy0Jf%7EPgRYyx1S9bxvnSFoTBI%7ERadl-Nmd8E_&Key-Pair-Id=01KXEF4KZ1B6FV465MAWR4M21F&Hash-Algorithm=SHA256"
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<token>/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 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
- **API Docs**: http://localhost:8000/docs
- **Qdrant Dashboard**: http://localhost:6333/dashboard

## 📖 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
```

## 🛠️ Troubleshooting

### Problemas de Build

```bash
# Limpar cache e rebuild
docker-compose build --no-cache
docker-compose down
docker-compose up -d
```

### Qdrant Não Inicia

```bash
# Remover volume existente
docker volume rm espiritismo_qdrant_data

# Reiniciar
docker-compose up -d qdrant
```

### Out of Memory

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

# Reiniciar
docker-compose restart celery
```

## 📈 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

## 🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se livre para:
- Reportar bugs
- Sugerir melhorias
- Enviar pull requests
- Adicionar novos livros

## 📄 Documentação

- **[BUILD.md](BUILD.md)** - Instruções detalhadas de build e deploy
- **[IMPLEMENTATION_COMPLETE.md](IMPLEMENTATION_COMPLETE.md)** - Relatório completo da implementação
- **[Design Document](docs/superpowers/specs/2025-11-01-espiritismo-rag-system-design.md)** - Design técnico detalhado
- **[Implementation Plan](docs/superpowers/plans/2025-11-01-espiritismo-rag-system.md)** - Plano de implementação

## 🔗 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/)

## 📄 Licença

MIT License - Veja o arquivo [LICENSE](LICENSE) para detalhes.

---

**Versão**: 1.0.0  
**Status**: ✅ Production Ready  
**Data**: 2026-11-01