Pular para conteúdo

Como Rodar Localmente (Setup para Novos Colaboradores)

Última atualização em 07/06/2026

Pré-requisitos

  • Python 3.13 instalado
  • uv instalado (gerenciador de pacotes)
  • Git instalado
  • Docker Desktop instalado (para uso do Supabase CLI localmente)
  • Conta no Google AI Studio para obter a GEMINI_API_KEY

Passo a Passo

  1. Fork este repositório.
  2. Clone o seu fork:
git clone https://github.com/SEU-USUARIO/vox-ai.git
cd vox-ai
  1. Instale o uv (Gerenciador de pacote):
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Mac/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Instale as dependências:
uv sync

Nota: Para adicionar novas bibliotecas, use uv add [NOME_DA_LIB].

  1. Configure as Variáveis de Ambiente: Crie um arquivo .streamlit/secrets.toml na raiz do projeto. O arquivo deve seguir este formato:
GEMINI_API_KEY = "SUA_CHAVE_AQUI"

[supabase]
url = "SUA_URL_SUPABASE"
key = "SUA_CHAVE_ANON_SUPABASE"

🔒 Suporte a Variáveis de Ambiente (OS): Como alternativa (ex: em contêineres Docker, nuvem ou CI/CD), você podeconfigurar as credenciais diretamente como variáveis de ambiente em caixa alta esublinhados: GEMINI_API_KEY, SUPABASE_URL e SUPABASE_KEY (ouSUPABASE_KEY_PROD no Gatekeeper).

  • Sem credenciais: O projeto rodará sem conexão com a base de dados doprojeto usando apenas a resposta da IA. Você verá avisos de conexão noterminal, o que é esperado.
  • Precisa de acesso ao banco? Se a feature que você deseja implementardepende estritamente do acesso ao banco de dados, envie um e-mail para a equipe.Podemos fornecer credenciais temporárias ou um ambiente de sandbox. 6. Instale os Git Hooks (Segurança): Para garantir que nenhum segredo seja commitado, que o banco de dados esteja consistente e que as mensagens de commit estejam no padrão, instale os hooks de pré-commit:
python scripts/install_hooks.py
  1. Execute o projeto:
uv run streamlit run vox_ai.py
  1. Acesse em: http://localhost:8501

Adicionar Novas Dependências

# Adicionar biblioteca:
uv add nome-da-biblioteca

Rodando os Testes

# Todos os testes unitários e de integração:
pytest

# Apenas testes unitários:
pytest tests/unit/

# Testes de integração (requerem credenciais reais):
pytest tests/integration/test_gemini_integration.py
pytest tests/integration/test_supabase_connection.py