lgcosta/espiritismo-rag-system
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
espiritismo-rag-system/docs/superpowers/specs/2025-11-01-espiritismo-rag-system-design.md
T
lgcosta b9c0c66d21 feat: implementar sistema RAG Espiritismo completo 
- 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
2026-11-01 10:56:17 -03:00

6.3 KiB
Raw Permalink Blame History

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.

Reference in new issue View Git Blame Copy Permalink