🐍 O que instalar na máquina
O HealthOS é enxuto de propósito: os scripts são Python puro (stdlib) — só o advice.py pede pip install requests. Antes de criar qualquer conta, deixe quatro ferramentas de base prontas na máquina. Você instala uma vez e segue para o resto.
🟢 Novo aqui? Dois termos antes de seguir
- CLI — "interface de linha de comando": um programa que você roda digitando no terminal, sem janela gráfica. O Supabase CLI é o que empurra o banco lá pra nuvem por comando.
- Runtime — o "motor" que executa um tipo de código. Python roda os scripts; Node roda o agente e o servidor do dashboard.
📊 Como ler: as quatro ferramentas de base (ciano, à esquerda) só precisam existir uma vez. Python e Node são obrigatórios; ffmpeg só entra se você for gerar clipes de treino; o Supabase CLI empurra o banco na Trilha 2.2.
| Ferramenta | Obrigatória? | Para quê |
|---|---|---|
| Python 3.9+ | Sim | Roda os scripts (stdlib). Só advice.py usa pip install requests. |
| Node | Sim | Roda o agente e o servidor do dashboard. |
| ffmpeg | Opcional | Só para exercise_clip.py (clipes de demonstração de treino). |
| Supabase CLI | Sim | Empurra as migrations (cria as 14 tabelas) — usado na 2.2. |
python3 --version && node --versionPython 3.11.6 e v20.11.0. Se o Python aparecer abaixo de 3.9 ou der "command not found", instale/atualize antes de seguir. (ffmpeg e Supabase CLI: cheque com ffmpeg -version e supabase --version — o primeiro só se for usar clipes.)Conceitos-chave
Os scripts não dependem de pacotes externos (quase nada a instalar).
Os dois motores obrigatórios: scripts e agente.
Só para clipes de treino.
Empurra o banco — protagonista da 2.2.
☁️ Criar o projeto Supabase privado
O Supabase é onde TODOS os seus dados de saúde vão morar — comida, treino, peso, exames, sinais vitais, metas e a memória das mensagens. Por isso ele tem que ser privado, na sua conta. Aqui você só cria o projeto e guarda quatro segredos; criar as tabelas é a 2.2.
🟢 Novo aqui?
Supabase é um banco de dados PostgreSQL na nuvem + armazenamento de arquivos, com um painel web. Pense nele como o "HD do coach": tudo que você registra vira uma linha lá, e o agente lê de lá a cada conversa.
Crie a conta e um projeto novo
Em supabase.com, "New project". O plano gratuito dá conta de uma pessoa.
Escolha uma região adequada
Prefira a região mais perto de você (menos latência). Para o Brasil, normalmente South America (São Paulo).
Defina e guarde a senha do banco
A senha do banco vira o SUPABASE_DB_PASSWORD — o Supabase CLI vai precisar dela na 2.2 para empurrar as migrations.
Copie URL e chaves (Settings → API)
Pegue o SUPABASE_URL, a SUPABASE_ANON_KEY (pública) e a SUPABASE_SERVICE_ROLE_KEY (servidor). Guarde para o tópico 6.
🔒 Anon × Service-role — duas chaves, dois mundos
A anon é pública; com a RLS ligada e sem políticas (você faz isso na 2.2), ela não lê nada. A service-role é a chave do servidor: ela ignora a RLS e tem acesso total. Por isso a service-role nunca vai pro navegador nem pro git — só pro ~/.env.
Conceitos-chave
O projeto é seu, na sua conta.
Perto de você = menos latência.
Vira DB_PASSWORD para as migrations.
Anon pública, service-role do servidor.
🤖 Criar o bot no Telegram (@BotFather)
O Telegram é a porta de entrada do coach: você conversa por mensagem. Para isso existir, você cria um bot com o @BotFather (o "bot que cria bots" oficial) e pega o token dele — o HEALTH_BOT_TOKEN.
Abra o @BotFather no Telegram
Procure por @BotFather (o verificado, com o selo azul) e inicie a conversa.
Mande /newbot e nomeie
Escolha um nome de exibição e um username terminando em bot (ex.: meu_health_os_bot).
Copie o token que ele te dá
Vem algo como 123456789:AAH...xyz. Esse é o HEALTH_BOT_TOKEN — guarde para o tópico 6.
⚠️ O token é a chave da porta
Qualquer um com o HEALTH_BOT_TOKEN controla o seu bot. Não cole em chat, não suba pro git. Se vazar, use /revoke no @BotFather para gerar um novo na hora.
💡 Onde o token é usado
Além do ~/.env, o agente aponta para essa variável no agent.yaml (campo telegram_bot_token_env). Você liga isso de fato na Trilha 2.3 — aqui é só ter o token na mão.
Conceitos-chave
O bot oficial que cria o seu bot.
Comando que gera o bot e o token.
A chave da porta de entrada.
Troca o token se ele vazar.
🔑 Chaves OpenAI e Gemini
Duas chaves cobrem dois trabalhos diferentes. A OpenAI gera os embeddings da memória (é como o coach lembra do seu histórico). O Gemini (Google) faz a visão: transforma a foto de uma comida ou de um exame em dado.
🟢 Novo aqui?
Embedding é transformar um texto num vetor de números que captura o "sentido". Mensagens parecidas viram vetores próximos — é assim que o coach acha o que você disse semanas atrás (memória semântica) em vez de só guardar a última fala.
🧠 OPENAI_API_KEY
- •Crie em
platform.openai.com→ API keys. - •Usada para embeddings da memória semântica.
- •Custo de embeddings é de centavos.
📸 GOOGLE_API_KEY
- •Crie em
aistudio.google.com→ Get API key. - •Visão Gemini: foto de comida → macros, exame → marcadores.
- •Custo de centavos por foto.
💰 Quanto pesa no bolso
Para uma pessoa, o uso típico fica em torno de US$ 10–20/mês somando as chamadas de LLM, com embeddings e visão em centavos. Configure um limite de gasto em cada conta para dormir tranquilo.
Conceitos-chave
OpenAI: a base da memória semântica.
Gemini: foto vira dado estruturado.
OpenAI e Google AI Studio.
Centavos por foto/embedding.
⌚ Conta WHOOP + app dev (opcional)
A WHOOP é o exemplo de wearable do blueprint, mas é 100% opcional. O mesmo padrão (OAuth + sync diário) serve para Oura, Garmin, Fitbit — ou registro manual. O coach e o dashboard trabalham com o que cair na tabela vitals, venha de onde vier.
🟢 Novo aqui?
OAuth é o aperto de mão que deixa o seu app ler os seus dados na WHOOP sem guardar a sua senha. Você autoriza uma vez; a WHOOP devolve um refresh_token que o sync usa (e rotaciona) a cada manhã.
✓ Tem WHOOP
- ✓Crie um app em
developer.whoop.com. - ✓Pegue o
WHOOP_CLIENT_IDe oWHOOP_CLIENT_SECRET. - ✓A API é gratuita com a assinatura. O
REFRESH_TOKENa callback preenche na 2.4.
○ Não tem WHOOP
- ○Deixe as três variáveis
WHOOP_*vazias. - ○Use outra wearable com o mesmo padrão, ou registre recovery/sono manualmente.
- ○Tudo o resto do curso funciona igual.
💡 Duas pegadinhas que a 2.4 resolve
Quando você ligar o sync de fato (Trilha 2.4), duas coisas mordem: a Cloudflare bane o user-agent padrão do Python (mande um de navegador) e o refresh-token precisa ser rotacionado a cada run. Aqui é só ter as credenciais — o resto vem lá.
Conceitos-chave
Qualquer fonte serve, até manual.
Gera CLIENT_ID e CLIENT_SECRET.
Autoriza sem guardar senha.
O destino comum de qualquer wearable.
📄 O arquivo ~/.env
Tudo o que você juntou — token, URL, chaves — converge para um único arquivo: o ~/.env, na sua home (o ~ é o atalho da sua pasta de usuário). Ele fica fora do git, sempre. O agente lê os segredos de lá para funcionar.
📊 Como ler: as cinco fontes (ciano, à esquerda) despejam suas chaves num só lugar — o ~/.env (azul, no centro). O agente lê só desse arquivo. A WHOOP entra tracejada porque é opcional.
Todas as variáveis, e para que servem
| Variável | Para quê |
|---|---|
| HEALTH_BOT_TOKEN | Token do bot do Telegram (do @BotFather). |
| SUPABASE_URL | Endereço do seu projeto: https://<ref>.supabase.co. |
| SUPABASE_SERVICE_ROLE_KEY | Acesso do servidor ao banco (ignora a RLS). Nunca no navegador. |
| SUPABASE_ANON_KEY | Chave pública — com RLS ligada, não lê nada. |
| SUPABASE_DB_PASSWORD | Senha do banco para o Supabase CLI rodar as migrations. |
| OPENAI_API_KEY | Embeddings da memória semântica. |
| GOOGLE_API_KEY | Visão Gemini (foto de comida / exame / treino). |
| DASHBOARD_TOKEN | Protege o dashboard web (um segredo aleatório seu). |
| WHOOP_CLIENT_ID | ID do seu app WHOOP (opcional). |
| WHOOP_CLIENT_SECRET | Segredo do seu app WHOOP (opcional). |
| WHOOP_REFRESH_TOKEN | Escrito pela callback OAuth, rotacionado a cada sync. |
# ~/.env — segredos do HealthOS. NUNCA versionar (fica na home, fora do git).
# Telegram (do @BotFather)
HEALTH_BOT_TOKEN=<seu-token-do-botfather>
# Supabase (Settings -> API e Database)
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>
SUPABASE_ANON_KEY=<anon-public-key>
SUPABASE_DB_PASSWORD=<senha-do-banco>
# Modelos
OPENAI_API_KEY=<sk-...>
GOOGLE_API_KEY=<sua-chave-gemini>
# Dashboard
DASHBOARD_TOKEN=<um-segredo-aleatorio-seu>
# WHOOP (OPCIONAL — qualquer wearable ou registro manual serve)
WHOOP_CLIENT_ID=<client-id-do-app-whoop>
WHOOP_CLIENT_SECRET=<client-secret-do-app-whoop>
WHOOP_REFRESH_TOKEN=<deixe-vazio-a-callback-preenche>~/.env. A dica do repo é copiar de agent/.env.example e preencher. Não sobrou nenhum <...>? Então está pronto para o próximo passo.# 1) o arquivo existe?
ls -l ~/.env
# 2) nenhum valor ficou como placeholder <...>?
grep -n '<' ~/.env || echo "OK: nenhum placeholder sobrando"ls deve listar o arquivo (se der "No such file", ele não está na home). O grep deve imprimir OK: nenhum placeholder sobrando — se listar linhas, ainda há <...> para trocar.⚠️ Nunca commitar o ~/.env
- •Ele mora na sua home (
~/.env), nunca num.envdentro do projeto. - •Fora do git, sempre. Quem tem essas chaves tem acesso aos seus dados de saúde.
- •Se vazar uma chave, revogue/regenere na conta de origem na hora.
Conceitos-chave
Tudo converge para o ~/.env.
~/.env, não dentro do projeto.
Segredo nunca é versionado.
3 delas (WHOOP) opcionais.
✅ Checklist de prontidão
Antes de seguir para o banco (Módulo 2.2), confirme que cada peça está no lugar. O diagrama abaixo mostra o que vai onde — qual chave alimenta qual capacidade do coach. Se tudo isso estiver de pé, você está pronto.
📊 Como ler: cada chave da esquerda (ciano) liga UMA capacidade do coach à direita (azul). Faltou a da esquerda? A da direita não acende. Só a última linha (WHOOP) é opcional — sem ela o coach roda igual, com registro manual.
✅ Você está pronto se…
- ✓
python3 --version≥ 3.9 enode --versionrespondem. - ✓Projeto Supabase privado criado, numa região adequada; URL + 2 chaves + senha do banco guardadas.
- ✓Bot criado no @BotFather;
HEALTH_BOT_TOKENna mão. - ✓
OPENAI_API_KEYeGOOGLE_API_KEYcriadas. - ✓(Opcional) app WHOOP criado, ou decidiu por registro manual.
- ✓
~/.envmontado e verificado — sem nenhum<...>sobrando.
✅ Auto-checagem (opcional): onde devem morar as suas chaves e segredos do HealthOS?
Conceitos-chave
Cada chave liga uma capacidade.
Sem a chave, a capacidade não acende.
A única linha que pode ficar vazia.
Tudo de pé → vamos ao banco.
📋 Resumo do módulo
Próximo módulo:
2.2 — O banco de dados: empurrar as migrations no Supabase, ligar o pgvector, criar as 14 tabelas e o bucket de fotos, e travar tudo com RLS.