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
• Setup de Desenvolvimento
• Executando Testes
• Estilo de Código
• Submetendo um Pull Request
• Reportando Bugs
• Sugerindo Features
• 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

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

2. Criar Ambiente Virtual

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

3. Instalar Dependências

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

docker-compose up -d

Opção C: PostgreSQL local

• Instale PostgreSQL + pgvector
• Crie database e configure .env

5. Configurar .env

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

6. Executar Migrações

python db/migrate.py

7. Testar Instalação

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

---

🧪 Executando Testes

Todos os Testes

pytest tests/ -v

Com Cobertura

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

Testes Específicos

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

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

Executar Linting

# 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

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

Linting

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

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

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

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

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

# 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

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.

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 - Overview do projeto
• docs/ARCHITECTURE.md - Arquitetura
• docs/ROADMAP.md - Plano de desenvolvimento

Guias Específicos

• docs/SUPABASE_SETUP.md - Setup Supabase
• 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! 🚀