🐍 Pré-requisitos e Python
O INTELECTO exige Python 3.11+ como mínimo absoluto. Versões anteriores não têm todas as features de async e tipagem que o projeto usa. As dependências são deliberadamente mínimas.
📦 requirements.txt Minimalista
python3 --version
Deve retornar Python 3.11 ou superior
python3 -m venv .venv && source .venv/bin/activate
Sempre use venv para isolamento
pip install -r requirements.txt
Instala apenas as 5 dependências necessárias
🔑 Conta OpenRouter
O OpenRouter é a escolha padrão para o INTELECTO porque resolve o problema de vendor lock-in com uma elegância cirúrgica: uma chave de API dá acesso a 100+ modelos, e mudar de modelo é apenas trocar uma string.
🎯 Por que OpenRouter?
- •100+ modelos: GPT-4o, Claude 3.5, Mistral, Llama 3, Gemini — todos com uma chave
- •Billing unificado: Um cartão, uma fatura, visibilidade de custo por modelo
- •Fallback automático: Se um modelo cair, você muda em segundos
- •Interface OpenAI-compatible: O mesmo código funciona sem mudanças
Criar conta em openrouter.ai
Ir em Keys → Create API Key
Copiar a chave (começa com sk-or-)
📝 Configuração do .env
O arquivo .env é a única fonte de configuração sensível. Nunca coloque chaves diretamente no código. O .env é carregado automaticamente pelo setup e NUNCA deve ir para o git.
📄 .env Exemplo Completo
⚠ Regra Crítica de Segurança
O .env deve estar no .gitignore. Verifique sempre antes de fazer commit. Uma chave de API exposta no GitHub pode gerar faturas de centenas de dólares em horas — isso acontece frequentemente com bots de scan automatizados.
🧙 O Wizard de Setup
O setup.py é um wizard interativo que faz as perguntas certas e configura tudo automaticamente. Ele cria os arquivos necessários, valida as credenciais e garante que nada obrigatório seja esquecido.
💬 Perguntas do Wizard
🐳 Docker vs Nativo
A escolha entre Docker e nativo afeta seu fluxo de trabalho. Para desenvolvimento, nativo é mais ágil. Para produção, Docker Compose garante reprodutibilidade e facilita o monitoramento.
🐍 Modo Nativo
- ✓Debug instantâneo com pdb/breakpoint
- ✓Reload automático com watchdog
- ✓Acesso direto ao filesystem
- ✗Depende do ambiente local
🐳 Modo Docker
- ✓Isolamento total do ambiente
- ✓Deploy reproduzível em qualquer servidor
- ✓Restart automático com --restart unless-stopped
- ✗Overhead de build e startup
📱 Primeira Mensagem no Telegram
O momento de verdade. Se a primeira mensagem funcionar, toda a stack está correta: canal conectado, provedor respondendo, memória inicializada e workspace carregado.
Criar Bot no BotFather
Abrir Telegram → BotFather → /newbot → seguir instruções → copiar o token que começa com números seguidos de :
Obter seu User ID
Enviar /start para @userinfobot no Telegram. Copiar o número retornado e colocar em TELEGRAM_ALLOWED_USERS.
Iniciar o INTELECTO
python main.py — aguardar "Bot iniciado. Aguardando mensagens..."
Enviar "Olá" e aguardar
O Jarvis vai responder com sua personalidade do SOUL.md. Se responder, parabéns — você tem um Jarvis funcionando.
💡 Smoke Test Checklist
- ✓Bot está rodando sem erros no terminal
- ✓Mensagem foi recebida (aparecer no log)
- ✓LLM foi chamado (custo no OpenRouter)
- ✓Resposta chegou no Telegram
- ✓audit.log tem o registro da interação
✅ Resumo do Módulo 1.3
Próxima Trilha:
Trilha 2 — Identidade e Canais: SOUL.md, AIEOS, Telegram, WhatsApp e memória SQLite