Como Rodar Localmente (Setup para Novos Colaboradores)¶
Última atualização em 07/06/2026
Pré-requisitos¶
- Python 3.13 instalado
uvinstalado (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¶
- Fork este repositório.
- Clone o seu fork:
git clone https://github.com/SEU-USUARIO/vox-ai.git
cd vox-ai
- 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
- Instale as dependências:
uv sync
Nota: Para adicionar novas bibliotecas, use
uv add [NOME_DA_LIB].
- Configure as Variáveis de Ambiente:
Crie um arquivo
.streamlit/secrets.tomlna 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_URLeSUPABASE_KEY(ouSUPABASE_KEY_PRODno 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
- Execute o projeto:
uv run streamlit run vox_ai.py
- 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