CONTRIBUTING.md

# 🤝 Contribuindo para RAG Template

Obrigado por considerar contribuir para o RAG Template! 🎉

Este projeto visa ser um template educativo e production-ready para sistemas RAG (Retrieval-Augmented Generation) com PostgreSQL + pgvector.

---

## 📋 Índice

- [Como Contribuir](#como-contribuir)
- [Setup de Desenvolvimento](#setup-de-desenvolvimento)
- [Executando Testes](#executando-testes)
- [Estilo de Código](#estilo-de-código)
- [Submetendo um Pull Request](#submetendo-um-pull-request)
- [Reportando Bugs](#reportando-bugs)
- [Sugerindo Features](#sugerindo-features)
- [Código de Conduta](#código-de-conduta)

---

## 🚀 Como Contribuir

Existem várias formas de contribuir:

1. **Reportar bugs** - Use os issue templates
2. **Sugerir features** - Abra uma feature request
3. **Melhorar documentação** - Correções, exemplos, tutoriais
4. **Submeter código** - Bug fixes, novas funcionalidades
5. **Revisar PRs** - Ajude a revisar pull requests de outros

---

## 🛠️ Setup de Desenvolvimento

### Pré-requisitos

- Python 3.10 ou superior
- PostgreSQL 15+ com pgvector
- Git

### 1. Fork e Clone

```bash
# Fork no GitHub primeiro, depois:
git clone https://github.com/SEU_USERNAME/rag_template.git
cd rag_template
```

### 2. Criar Ambiente Virtual

```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows
```

### 3. Instalar Dependências

```bash
pip install -r requirements.txt

# Para desenvolvimento, instale também:
pip install pytest pytest-cov black ruff mypy
```

### 4. Configurar Banco de Dados

Você tem algumas opções:

**Opção A: Supabase (recomendado para desenvolvimento)**
- Siga o guia em `docs/SUPABASE_SETUP.md`
- Ou use o script: `python scripts/setup_supabase.py`

**Opção B: Docker local**
```bash
docker-compose up -d
```

**Opção C: PostgreSQL local**
- Instale PostgreSQL + pgvector
- Crie database e configure `.env`

### 5. Configurar `.env`

```bash
cp .env.example .env
# Edite .env com suas configurações
```

### 6. Executar Migrações

```bash
python db/migrate.py
```

### 7. Testar Instalação

```bash
python app.py
# Acesse http://localhost:7860
```

---

## 🧪 Executando Testes

### Todos os Testes

```bash
pytest tests/ -v
```

### Com Cobertura

```bash
pytest tests/ --cov=src --cov=ui --cov-report=html
# Abra htmlcov/index.html no navegador
```

### Testes Específicos

```bash
# Módulo específico
pytest tests/test_embeddings.py -v

# Teste específico
pytest tests/test_embeddings.py::TestEmbeddingManager::test_encode -v
```

### Executar Linting

```bash
# Ruff (linter)
ruff check src/ ui/ tests/

# Black (formatter)
black --check src/ ui/ tests/

# MyPy (type checker)
mypy src/ --ignore-missing-imports
```

---

## 🎨 Estilo de Código

Seguimos as convenções da comunidade Python:

### Formatação

- **Black** para formatação automática
- Linha máxima: 100 caracteres
- Aspas duplas para strings

```bash
# Formatar código
black src/ ui/ tests/
```

### Linting

- **Ruff** para linting (substitui flake8, isort, etc)
- Seguimos PEP 8 com algumas exceções

```bash
# Verificar código
ruff check src/ ui/ tests/

# Auto-fix quando possível
ruff check --fix src/ ui/ tests/
```

### Type Hints

- Use type hints em todas as funções públicas
- Especialmente importante em `src/`

```python
# ✅ Bom
def encode_text(text: str, normalize: bool = True) -> np.ndarray:
    ...

# ❌ Evite
def encode_text(text, normalize=True):
    ...
```

### Docstrings

- Use docstrings para classes e funções públicas
- Formato: Google Style

```python
def search_similar(
    self,
    query_embedding: np.ndarray,
    k: int = 5
) -> List[Dict[str, Any]]:
    """
    Busca documentos similares usando busca vetorial.

    Args:
        query_embedding: Vetor de embedding da query
        k: Número de resultados a retornar

    Returns:
        Lista de documentos com scores de similaridade
    """
    ...
```

---

## 📤 Submetendo um Pull Request

### 1. Crie uma Branch

```bash
# Para features
git checkout -b feature/nome-descritivo

# Para bug fixes
git checkout -b fix/descricao-bug

# Para documentação
git checkout -b docs/descricao
```

### 2. Faça Suas Mudanças

- Escreva código limpo e testável
- Adicione/atualize testes
- Atualize documentação relevante
- Siga o estilo de código

### 3. Commit

Use mensagens de commit claras:

```bash
# Formato: <tipo>: <descrição>

# Tipos:
# - feat: Nova funcionalidade
# - fix: Bug fix
# - docs: Documentação
# - style: Formatação
# - refactor: Refatoração
# - test: Testes
# - chore: Manutenção

# Exemplos:
git commit -m "feat: add hybrid search with BM25"
git commit -m "fix: resolve connection timeout in database"
git commit -m "docs: update README with new features"
```

### 4. Push

```bash
git push origin sua-branch
```

### 5. Abra Pull Request

- Vá para o GitHub e abra um PR
- Preencha o template de PR
- Aguarde review

### Checklist do PR

Antes de submeter, verifique:

- [ ] Código segue o style guide
- [ ] Testes foram adicionados/atualizados
- [ ] Todos os testes passam localmente
- [ ] Documentação foi atualizada
- [ ] CHANGELOG.md foi atualizado (se aplicável)
- [ ] Sem conflitos com branch main

---

## 🐛 Reportando Bugs

Use o template de bug report:

1. Vá para Issues → New Issue
2. Escolha "Bug Report"
3. Preencha todas as seções:
   - Descrição clara do bug
   - Passos para reproduzir
   - Comportamento esperado vs atual
   - Ambiente (OS, Python version, etc)
   - Logs relevantes

**Dica**: Quanto mais detalhes, mais rápido conseguimos resolver!

---

## 💡 Sugerindo Features

Use o template de feature request:

1. Vá para Issues → New Issue
2. Escolha "Feature Request"
3. Explique:
   - Que problema resolve
   - Solução proposta
   - Alternativas consideradas
   - Contexto adicional

---

## 📜 Código de Conduta

Este projeto adota o [Contributor Covenant](CODE_OF_CONDUCT.md).

Ao participar, você concorda em respeitar este código.

### Resumo

- ✅ Seja respeitoso e inclusivo
- ✅ Aceite feedback construtivo
- ✅ Foque no que é melhor para a comunidade
- ❌ Não use linguagem ofensiva
- ❌ Não faça ataques pessoais

---

## 🏆 Reconhecimento

Todos os contribuidores são reconhecidos:

- Nome listado em CONTRIBUTORS.md
- Menção em CHANGELOG.md
- Badge de contributor no GitHub

---

## 📚 Recursos Úteis

### Documentação

- [README.md](README.md) - Overview do projeto
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Arquitetura
- [docs/ROADMAP.md](docs/ROADMAP.md) - Plano de desenvolvimento

### Guias Específicos

- [docs/SUPABASE_SETUP.md](docs/SUPABASE_SETUP.md) - Setup Supabase
- [docs/PHASE_3_SUMMARY.md](docs/PHASE_3_SUMMARY.md) - Features avançadas

### Tutoriais

- Veja `examples/` para exemplos práticos
- Veja `notebooks/` para análises exploratórias

---

## 💬 Dúvidas?

- Abra uma issue com label "question"
- Veja discussões existentes
- Consulte a documentação

---

## 🙏 Obrigado!

Sua contribuição torna este projeto melhor para todos! 🎉

Seja você corrigindo um typo ou implementando uma feature complexa, toda ajuda é bem-vinda e valorizada.

Happy coding! 🚀