README.md

---
title: RAG Template
emoji: 📚
colorFrom: yellow
colorTo: red
sdk: gradio
sdk_version: 4.36.0
app_file: app.py
pinned: false
license: mit
---

#  RAG Template Educativo

**Template interativo de Retrieval-Augmented Generation com PostgreSQL + pgvector**

Uma aplicação educativa completa que demonstra cada etapa do processo RAG de forma visual e interativa.

[![CI](https://github.com/guifav/rag_template/workflows/CI/badge.svg)](https://github.com/guifav/rag_template/actions)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-pgvector-336791.svg)](https://github.com/pgvector/pgvector)
[![Gradio](https://img.shields.io/badge/Gradio-UI-orange.svg)](https://gradio.app/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

##  Funcionalidades

###  Ingestão de Documentos
- Upload de arquivos PDF e TXT
- Visualização do texto extraído
- **4 estratégias de chunking** (tamanho fixo, por sentenças, semântico, recursivo)
- Preview de embeddings gerados
- Estatísticas detalhadas do processo
- **Cache automático de embeddings** para performance

###  Exploração da Base de Conhecimento
- Busca semântica interativa
- Visualização de scores de similaridade
- Listagem de todos os documentos armazenados
- Análise de relevância dos resultados

###  Chat RAG Interativo
- Interface de chat com IA
- **Suporte a 4 LLM providers** (HuggingFace, OpenAI, Anthropic, Ollama)
- Painel lateral mostrando contextos recuperados
- Visualização do prompt construído
- Métricas de performance em tempo real
- Controles de parâmetros (top_k, temperature, max_tokens)

###  Playground de Parâmetros
- Comparação lado a lado de configurações
- Experimente com diferentes top_k, temperature, max_tokens
- Análise comparativa de resultados
- Entenda o impacto de cada parâmetro

###  Comparação de Chunking (NOVO)
- Teste 4 estratégias de chunking no mesmo texto
- Visualização lado a lado dos resultados
- Estatísticas comparativas detalhadas
- Entenda o impacto de cada abordagem

###  Monitoramento e Métricas
- Dashboard de estatísticas gerais
- Métricas de performance (latências)
- Histórico de queries
- Análise de uso do sistema
- **Logging estruturado** em JSON

###  Sistema de Filtros e Metadados (NOVO)
- Metadados extensiveis em JSONB
- 8 tipos de filtros (tipo, tags, autor, departamento, security_level, datas)
- Busca vetorial combinada com filtros SQL
- Performance otimizada com indices GIN
- Controle de acesso por nivel de seguranca
- Multi-tenancy basico

###  Avaliacao de Qualidade RAG (NOVO)
- Framework RAGAS com 4 metricas principais
- Faithfulness, Answer Relevancy, Context Precision, Context Recall
- Fallback para metricas simplificadas (sem RAGAS)
- Sistema de benchmarking automatizado
- Relatorios HTML com visualizacoes
- Comparacao de multiplas configuracoes

---

##  Arquitetura

```
┌─────────────────────────────────────────────────────────────┐
│                    Interface Gradio                          │
│  (Ingestão | Exploração | Chat | Playground | Métricas)    │
└────────────────────┬────────────────────────────────────────┘
                     │
          ┌──────────┴───────────┐
          │   App Controller     │
          └──────────┬───────────┘
                     │
      ┌──────────────┼──────────────┐
      │              │              │
┌─────▼─────┐  ┌────▼────┐  ┌─────▼──────┐
│ Embedding │  │  RAG    │  │ Generation │
│  Manager  │  │ Pipeline│  │  Manager   │
└─────┬─────┘  └────┬────┘  └─────┬──────┘
      │             │              │
      └─────────────┼──────────────┘
                    │
         ┌──────────▼───────────┐
         │  Database Manager    │
         │  (PostgreSQL +       │
         │   pgvector)          │
         └──────────────────────┘
```

---

##  Início Rápido

### Pré-requisitos

- Python 3.10+
- PostgreSQL com extensão pgvector
- Token da Hugging Face (para geração de texto)

### Opção 1: Docker Compose (Recomendado para desenvolvimento)

```bash
# Clone o repositório
git clone https://github.com/guifav/rag_template.git
cd rag_template

# Inicie o PostgreSQL com pgvector
docker compose up -d

# Crie ambiente virtual e instale dependências
python -m venv .venv
source .venv/bin/activate  # No Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Configure variáveis de ambiente
cp .env.example .env
# Edite .env e adicione seu HF_TOKEN

# Execute a aplicação
python app.py
```

Acesse: http://localhost:7860

### Opção 2: Supabase (Recomendado para produção)

1. Crie uma conta no [Supabase](https://supabase.com)
2. Crie um novo projeto
3. Habilite a extensão `vector` em Database > Extensions
4. Copie a string de conexão em Project Settings > Database
5. Configure no `.env`:

```bash
DATABASE_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT_REF].supabase.co:5432/postgres
HF_TOKEN=seu_token_aqui
```

6. Execute o app:

```bash
python app.py
```

 [Guia completo de setup Supabase](docs/SUPABASE_SETUP.md)

---

##  Estrutura do Projeto

```
rag_template/
├── app.py                      # Aplicação principal
├── requirements.txt            # Dependências Python
├── docker-compose.yml          # PostgreSQL local
├── .env.example                # Template de configuração
│
├── src/                        # Módulos principais
│   ├── config.py              # Configurações centralizadas
│   ├── database.py            # Gerenciamento do banco
│   ├── embeddings.py          # Geração de embeddings
│   ├── chunking.py            # Estratégias de chunking
│   ├── document_processing.py # Extração de texto
│   └── generation.py          # Geração de respostas
│
├── ui/                         # Componentes da interface
│   ├── ingestion_tab.py       # Aba de ingestão
│   ├── exploration_tab.py     # Aba de exploração
│   ├── chat_tab.py            # Aba de chat
│   ├── playground_tab.py      # Aba de playground
│   └── monitoring_tab.py      # Aba de monitoramento
│
├── docs/                       # Documentação
│   └── SUPABASE_SETUP.md      # Guia de setup Supabase
│
├── db/init/                    # Scripts de inicialização
│   ├── 01_init.sql            # Extensão pgvector
│   └── 02_indexes.sql         # Índices otimizados
│
└── tests/                      # Testes automatizados
    ├── test_units.py
    └── test_integration_db.py
```

---

##  Configuração

### Variáveis de Ambiente

```bash
# Banco de Dados
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/ragdb

# Hugging Face
HF_TOKEN=seu_token_aqui
HF_MODEL_ID=HuggingFaceH4/zephyr-7b-beta

# Embeddings
EMBEDDING_MODEL_ID=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DIM=384

# Retrieval
TOP_K=4
IVFFLAT_LISTS=100

# Chunking
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

# Geração
TEMPERATURE=0.3
MAX_TOKENS=512

# App
PORT=7860
```

### Modelos Alternativos

**LLMs:**
- `mistralai/Mistral-7B-Instruct-v0.2`
- `meta-llama/Llama-2-7b-chat-hf`
- `google/flan-t5-large`

**Embeddings:**
- `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` (multilíngue)
- `sentence-transformers/all-mpnet-base-v2` (melhor qualidade, 768d)
- `BAAI/bge-small-en-v1.5` (eficiente)

---

##  Como Usar

### 1. Ingerir Documentos

1. Vá na aba ** Ingestão de Documentos**
2. Faça upload de arquivos PDF ou TXT
3. Escolha a estratégia de chunking
4. Ajuste o tamanho dos chunks
5. Clique em **Iniciar Ingestão**
6. Acompanhe cada etapa do processo

### 2. Explorar a Base

1. Vá na aba ** Exploração da Base**
2. Visualize estatísticas do banco
3. Digite uma query de busca
4. Veja os resultados ranqueados por similaridade
5. Analise os scores de relevância

### 3. Conversar com RAG

1. Vá na aba ** Chat RAG**
2. Ajuste os parâmetros (top_k, temperature, max_tokens)
3. Digite sua pergunta
4. Veja os contextos recuperados no painel lateral
5. Analise o prompt construído
6. Receba resposta com fontes

### 4. Experimentar Parâmetros

1. Vá na aba ** Playground de Parâmetros**
2. Configure duas configurações diferentes
3. Execute ambas com a mesma query
4. Compare os resultados lado a lado
5. Entenda o impacto de cada parâmetro

### 5. Monitorar Uso

1. Vá na aba ** Monitoramento**
2. Veja estatísticas gerais do sistema
3. Analise métricas de performance
4. Visualize histórico de queries

---

##  Desenvolvimento

### Instalação para Desenvolvimento

```bash
# Clone e entre no diretório
git clone https://github.com/guifav/rag_template.git
cd rag_template

# Ambiente virtual
python -m venv .venv
source .venv/bin/activate

# Dependências
pip install -r requirements.txt

# Iniciar banco local
docker compose up -d

# Configurar .env
cp .env.example .env
# Edite .env com suas credenciais

# Executar testes
pytest tests/

# Executar app
python app.py
```

### Adicionar Nova Funcionalidade

1. Crie um módulo em `src/` se necessário
2. Crie uma aba em `ui/` se for componente de UI
3. Integre no `app.py`
4. Adicione testes em `tests/`
5. Atualize documentação

---

## Deploy

O projeto oferece múltiplas opções de deploy documentadas:

### Hugging Face Spaces (Recomendado para Demo)
- Deploy com um clique
- Free tier com 16GB RAM
- Documentação completa em [README_SPACES.md](README_SPACES.md)
- Guia de secrets: [docs/SPACES_SECRETS.md](docs/SPACES_SECRETS.md)

### Railway (Full-Stack Deployment)
- App + PostgreSQL juntos
- CI/CD integrado com GitHub
- Guia completo: [docs/RAILWAY_SETUP.md](docs/RAILWAY_SETUP.md)

### Docker (Produção Local)
- Stack completa com docker-compose
- Multi-stage build otimizado
- Guia: [DEPLOY.md](DEPLOY.md#3-docker-localproducao)

### VPS/Cloud (AWS, DigitalOcean, etc)
- Controle total
- Setup com Docker
- Guia: [DEPLOY.md](DEPLOY.md#4-vpscloud-digitalocean-aws-etc)

Veja o [Guia Completo de Deploy](DEPLOY.md) para instruções detalhadas.

---

##  Performance e Escalabilidade

### Otimizações Implementadas

- DONE Índice IVFFLAT para busca vetorial eficiente
- DONE Connection pooling (Supabase)
- DONE Lazy loading de modelos
- DONE Embeddings normalizados (cosine similarity)
- DONE Batch processing na ingestão

### Limites Recomendados

- **Documentos**: Até 100k chunks no free tier Supabase (500MB)
- **Chunk size**: 500-1500 caracteres (depende do domínio)
- **Top K**: 3-10 para maioria dos casos
- **Embedding model**: 384d para velocidade, 768d para qualidade

---

##  Contribuindo

Contribuições são bem-vindas! Este projeto aceita contribuições via Pull Requests.

### Como Contribuir

1. Fork o projeto
2. Crie uma branch (`git checkout -b feature/MinhaFeature`)
3. Commit suas mudanças (`git commit -m 'Add: MinhaFeature'`)
4. Push para a branch (`git push origin feature/MinhaFeature`)
5. Abra um Pull Request

### Guias

- Leia o [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes sobre setup de desenvolvimento
- Use os issue templates para reportar bugs ou sugerir features
- Siga o estilo de código (black + ruff)
- Adicione testes para novas funcionalidades

### Reportando Bugs

Use o [Bug Report template](.github/ISSUE_TEMPLATE/bug_report.md) e inclua:
- Descrição clara do problema
- Passos para reproduzir
- Ambiente (OS, Python version, etc)
- Logs relevantes

---

## Roadmap

### Completo (Janeiro 2026)
- **Fase 1**: Interface Educativa (8 abas interativas)
- **Fase 2**: Melhorias Tecnicas (Multi-LLM, Chunking Avancado, Cache, Logging)
- **Fase 3**: RAG Avancado (Reranking, Hybrid Search, Visualizacoes, Query Expansion)
- **Fase 4**: Deploy e Distribuicao (HF Spaces, CI/CD, Docker, Railway, Neon)
- **Fase 5**: Recursos Educativos (Tutoriais, FAQ, Notebooks, Diagramas)
- **Fase 6**: Funcionalidades Avancadas e Producao - 100% COMPLETO
  - Sistema de filtros e metadados (Completo)
  - Avaliacao automatica com RAGAS (Completo)
  - API REST + SDK Python (Completo)
  - Observabilidade (Prometheus, OpenTelemetry) (Completo)
  - Melhorias de UX (dark mode, shortcuts, export) (Completo)
  - Testes abrangentes (>85% cobertura) (Completo)

### Versao Atual: 2.0.0 - Production-Ready Enterprise System

O RAG Template agora e um sistema completo production-ready enterprise com:
- API REST completa para integracao
- Python SDK para desenvolvimento rapido
- Monitoring com Prometheus e OpenTelemetry
- Testes abrangentes (>85% cobertura)
- UX moderna com dark mode e shortcuts
- Sistema de export completo
- Documentacao completa (3000+ linhas)

Veja o [ROADMAP completo](docs/ROADMAP.md), [Plano da Fase 6](docs/PHASE_6_PLAN.md) e [Resumo Final da Fase 6](docs/FASE_6_RESUMO_FINAL.md) para detalhes.

---

##  Problemas Conhecidos

- Conexão Supabase pode demorar alguns segundos no cold start
- Modelos grandes de embedding podem consumir muita RAM
- Algumas queries podem ter latência alta (>5s) dependendo do modelo LLM

Reporte bugs em: https://github.com/guifav/rag_template/issues

---

## Recursos Adicionais

### Tutoriais e Aprendizado
- [Tutorial: Getting Started](docs/tutorials/01_getting_started.md) - Primeiros passos (15-20min)
- [FAQ](docs/FAQ.md) - 40+ perguntas frequentes
- [Use Case: Technical Docs Chatbot](docs/tutorials/use_cases/technical_docs_chatbot.md) - Caso pratico
- [Notebooks Jupyter](notebooks/) - Aprendizado interativo hands-on
  - [01_rag_basics.ipynb](notebooks/01_rag_basics.ipynb) - Fundamentos de RAG
  - [02_advanced_rag.ipynb](notebooks/02_advanced_rag.ipynb) - Tecnicas avancadas
- [Diagramas Arquiteturais](docs/diagrams/rag_flow.md) - 7 diagramas mermaid

### Documentação do Projeto
- [CONTRIBUTING.md](CONTRIBUTING.md) - Guia de contribuição
- [CHANGELOG.md](CHANGELOG.md) - Histórico de versões
- [ROADMAP.md](docs/ROADMAP.md) - Planejamento futuro
- [DEPLOY.md](DEPLOY.md) - Guia completo de deploy
- [PROJECT_STATUS.md](docs/PROJECT_STATUS.md) - Status completo do projeto
- [PHASE_6_PLAN.md](docs/PHASE_6_PLAN.md) - Plano detalhado da Fase 6
- [FASE_6_RESUMO_FINAL.md](docs/FASE_6_RESUMO_FINAL.md) - Resumo da implementacao Fase 6
- [METADATA_GUIDE.md](docs/METADATA_GUIDE.md) - Guia completo de metadados e filtros

### Guias de Database
- [Supabase Setup](docs/SUPABASE_SETUP.md)
- [Neon Setup](docs/NEON_SETUP.md)
- [Railway Setup](docs/RAILWAY_SETUP.md)
- [Comparação de Providers](docs/DATABASE_COMPARISON.md)

### Documentação Externa
- [Documentação pgvector](https://github.com/pgvector/pgvector)
- [Sentence Transformers](https://www.sbert.net/)
- [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index)
- [Gradio Docs](https://www.gradio.app/docs/)

---

## 📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.

---

##  Créditos

Desenvolvido com:
- [PostgreSQL](https://www.postgresql.org/) + [pgvector](https://github.com/pgvector/pgvector)
- [Sentence Transformers](https://www.sbert.net/)
- [Hugging Face](https://huggingface.co/)
- [Gradio](https://gradio.app/)
- [Supabase](https://supabase.com/)

---

##  Dúvidas?

- 📖 Leia a [documentação completa](docs/)
-  Abra uma [issue](https://github.com/guifav/rag_template/issues)
- 🌟 Dê uma estrela se este projeto foi útil!

---

**Feito com  para a comunidade de IA**