health-os

Personal AI health system: a self-hosted store for your medical data (labs, diagnoses, medications, device data, food log) with deterministic safety checks and a Claude MCP interface. The design plan and personal documents are kept privately, outside this repository.

Medical disclaimer. This is not a medical device and does not give medical advice. Critical-value alerts and screening reminders are only a signal to contact a doctor — never a diagnosis and never a reason to delay care. Use at your own risk.

Stack

Python 3.13 · PostgreSQL 16 (Docker) · SQLAlchemy · Alembic · FastMCP · FastAPI · aiogram · APScheduler. pgvector is enabled in Phase 3 (the image already has it), not earlier.

Related MCP server: indaga-agent

Structure

health-os/
├── docker-compose.yml     # Postgres 16 (pgvector image)
├── alembic.ini
├── migrations/            # Alembic; 0001 = schema v3 (Part 3 of the plan)
├── core/                  # config, db, (Phase 1: models, schemas, services, normalize/)
├── ingestion/             # Phase 1: pipeline (state machine), extractors/, importers/
├── mcp_server/            # Phase 1
├── api/                   # Phase 4 (planned, not yet created)
├── worker/                # APScheduler: recomputation, cron reports, device_samples partitions
├── bot/                   # Phase 4 (aiogram; planned, not yet created)
├── analytics/             # Phase 5
├── safety/                # Phase 1: critical_values, red_flags, crisis — deterministic code
├── evals/                 # Phase 1: golden set + red-team
├── prompts/               # versioned prompts
├── seed/                  # observation_types, synonyms, unit_conversions, reference_ranges
└── data/                  # files, backups (outside git)

Quick start (Phase 0)

cp .env.example .env          # edit passwords
docker compose up -d          # bring up Postgres 16
uv sync                       # or: python3 -m venv .venv && pip install -e .
uv run alembic upgrade head   # schema v3
uv run python -m seed.load    # marker reference data

Phase 0 criterion: docker compose up → live database; alembic upgrade head without errors; seed loaded; backup→restore test passed; FileVault enabled (fdesetup status).

Tests

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`

Tests that need the database carry the integration marker — added automatically for tests using the conn/user_id fixtures, or via pytestmark for modules that use engine directly.

Integration tests never touch the working database: tests/conftest.py drops and recreates <POSTGRES_DB>_test on the same Postgres server (migrations + seed) on every run. Override with TEST_DATABASE_URL (the database name must end in _test). If Postgres is down, integration tests are skipped; unit tests still run.

Privacy

• data/ and .env — outside git (see .gitignore).

• FileVault is mandatory (otherwise PHI is on disk in plaintext).

• Real medical data to Anthropic — only via the API with commercial/ZDR terms.

• Never put real medical data in issues, PRs or tests — synthetic data only.

License

AGPL-3.0-or-later. You may use, modify and fork health-os; if you distribute it or run a modified version as a network service, you must publish your source under the same license.

Want to use it in a closed-source or commercial product without those obligations? A separate commercial license is available from the author — reach out via GitHub (@andronaft).

Contributions are welcome — see CONTRIBUTING.md (includes a short CLA).