health-os

health-os

Registro de saúde pessoal local-first, exposto via MCP. Seus exames laboratoriais, diagnósticos, medicamentos, dados de wearables e diário alimentar ficam no seu próprio Postgres; qualquer cliente MCP — seja um executando um modelo local ou um assistente em nuvem — pode ler e atualizar esses dados por meio de ferramentas protegidas. Valores críticos, regras de segurança de medicamentos e cronogramas de triagem são código determinístico, não julgamento de LLM.

Aviso médico. Isto não é um dispositivo médico e não fornece aconselhamento médico. Alertas de valores críticos e lembretes de triagem são apenas um sinal para contatar um médico — nunca um diagnóstico e nunca um motivo para adiar cuidados. Use por sua conta e risco.

O que faz

• Resultados de exames laboratoriais — envie um PDF ou foto para o seu cliente MCP; o modelo extrai os valores, o health-os normaliza nomes (sinônimos em uk/ru/en/Latim) e unidades, e prepara o painel como pendente. Nada conta como fato até que você aprove.
• Rede de segurança em código — valores críticos alertam imediatamente (log, notificação macOS, Telegram opcional); achados críticos em relatórios narrativos são sinalizados; perguntas sobre interações medicamentosas são recusadas e redirecionadas a um médico/farmacêutico (apenas verificações determinísticas são executadas: dose diária total de paracetamol entre produtos, biotina antes de exames laboratoriais); uma ferramenta de crise retorna uma resposta fixa com linhas de emergência, independente do modelo.
• Tendências e análises — tendências Mann-Kendall, linhas de base pessoais e anomalias, calculadoras de risco por faixa etária, um calendário de triagem, um relatório semanal, um resumo para consulta médica.
• Diário alimentar — refeições com perfil de 41 nutrientes, %RDA, sinalizações de deficiência/excesso, modelos de refeição.
• Dispositivos — importação do Apple Health e do Garmin.
• 28 ferramentas MCP + instruções do servidor — as regras de segurança são enviadas a cada cliente na conexão; veja mcp_server/README.md.

Experimente com um comando

Apenas Docker é necessário. Inicia um banco de dados descartável com um paciente fictício — dois anos de exames (LDL aumentando gradualmente), pressão arterial, medicamentos, um diário alimentar e um painel de exames aguardando aprovação:

git clone https://github.com/andronaft/health-os && cd health-os/demo
docker compose up -d --build

Aponte seu cliente MCP para ele:

{
  "mcpServers": {
    "health-os-demo": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "health-os-demo",
               "-e", "DATABASE_URL=postgresql+psycopg://health:demo@db:5432/health_os",
               "health-os:local"]
    }
  }
}

Pergunte "mostre meu resumo de saúde", "meu LDL está em tendência de alta?", "o que está aguardando revisão?", "do que estou carente nutricionalmente?". Remova tudo com docker compose down -v.

Instale para seus próprios dados

Requer Docker e Python 3.12+.

git clone https://github.com/andronaft/health-os && cd health-os
cp .env.example .env                  # set the passwords
docker compose up -d db               # Postgres 16 + pgvector
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/alembic upgrade head        # schema
.venv/bin/python -m seed.load         # marker catalog, synonyms, units, nutrients
.venv/bin/python -m seed.demo         # optional: a fictional demo patient to play with

Em seguida, conecte um cliente MCP — configuração para LM Studio, Open WebUI, Ollama CLI e Claude está em mcp_server/README.md. Experimente: "mostre meu resumo de saúde", "tendência do LDL", "do que estou carente nutricionalmente esta semana?".

Modelos locais: o servidor fala MCP padrão via stdio, então qualquer cliente MCP que execute um modelo local pode usá-lo. Verificado até agora: o próprio servidor com o cliente Python MCP oficial (CI + a demonstração Docker). Ainda não verificado de ponta a ponta com um modelo local — veja #9; relatos são bem-vindos.

Como funciona

MCP client (local or cloud model)
        │ stdio
   mcp_server/  ── read tools ──▶ approved views (read-only role, 5s timeout, row limits)
        │        ── write tools ─▶ core/services: normalize → status → critical rules → pending
        │
   safety/    critical values, narrative flags, interactions, crisis, alerts
   analytics/ trends, baselines, calculators, screening, nutrition, weekly report
        │
   PostgreSQL 16 + pgvector  ◀── ingestion/ (Apple Health, Garmin, embeddings)

Diretório	O que contém
core/	configuração, banco de dados, normalização, serviços, deduplicação, resumo de saúde
mcp_server/	servidor MCP, ferramentas de leitura e escrita
safety/	regras de segurança determinísticas e entrega de alertas
analytics/	tendências, linhas de base, calculadoras, triagem, nutrição, relatórios
ingestion/	esquema de extração, pontuação de confiança, importadores de dispositivos, embeddings
migrations/	esquema Alembic
seed/	catálogo de referência + o paciente de demonstração
evals/	cenários de red-team (injeções, valores críticos ocultos, truques de unidades)
scripts/	backup/restauração (restic + launchd), configuração de papel somente leitura, importadores

Privacidade / local-first

• Seus dados permanecem no seu próprio banco de dados. O Postgres roda localmente no Docker; data/ e .env estão fora do git. Nada é enviado a lugar algum pelo próprio health-os.
• O que sai da máquina depende do cliente MCP que você conecta. Com um modelo local (LM Studio, Open WebUI + Ollama, …) nada sai. Com um assistente em nuvem, o que as ferramentas retornam é enviado a esse provedor — use um cujos termos sejam adequados a dados médicos (sem treinamento com seus dados, retenção zero/curta).
• O objetivo é totalmente local: modelos locais para chat e extração, embeddings locais para busca (já suportados via fastembed). Clientes em nuvem permanecem opcionais.
• O canal de alerta opcional (Telegram) envia apenas um texto genérico "verifique seu sistema de saúde", nunca valores.
• Criptografe o disco (FileVault / LUKS / BitLocker) — os arquivos do banco de dados ficam em texto puro em repouso.
• Nunca coloque dados médicos reais em issues, PRs ou testes — apenas dados sintéticos.

Testes

make test              # everything (needs Postgres for the integration part)
make test-unit         # pure unit tests — no database needed
make test-integration  # only tests marked `integration`

Os testes de integração nunca tocam o banco de dados de trabalho: tests/conftest.py remove e recria <POSTGRES_DB>_test no mesmo servidor (migrações + seed) a cada execução. Substitua com TEST_DATABASE_URL (o nome deve terminar em _test). Sem Postgres, os testes de integração são ignorados localmente; o CI define REQUIRE_DB=1 para que eles falhem em vez disso.

Histórico de desenvolvimento: PROGRESS.md.

Licença

AGPL-3.0-or-later. Você pode usar, modificar e fazer fork do health-os; se você o distribuir ou executar uma versão modificada como serviço de rede, deve publicar seu código-fonte sob a mesma licença.

Quer usá-lo em um produto de código fechado ou comercial sem essas obrigações? Uma licença comercial separada está disponível com o autor — entre em contato via GitHub (@andronaft).

Contribuições são bem-vindas — veja CONTRIBUTING.md (inclui um CLA curto).