---

The Problem

The healthcare system is overwhelming. Medical bills are incomprehensible. Insurance denials feel final. Discharge instructions are written in a language you don't speak. And every step of the way, you're expected to advocate for yourself — often when you're at your most vulnerable.

HealthAdvocate exists to change that.

It's a free, open-source tool that sits on your machine and helps you:

• Understand what your symptoms might mean — and how urgent they are
• Decode medical bills and spot suspicious charges
• Fight back when insurance denies your claim — with a drafted appeal letter
• Translate discharge instructions into language you can actually follow
• Prepare for doctor visits with talking points and questions to ask
• Check drug information, side effects, and cheaper alternatives
• Separate real health advice from misinformation online

Your data stays on your device by default. No accounts, no cloud service, no tracking, no telemetry. Ever.

---

Features

Symptom Assessment

Describe how you feel in your own words. Two AI layers — medical entity recognition and clinical reasoning — cross-validate each other to give you a reliable urgency assessment, possible conditions, and clear next steps. If they disagree on urgency, the system defaults to "high" for your safety.

Insurance Denial Fighter

Paste your denial letter. HealthAdvocate identifies the denial reason, builds specific appeal arguments, and generates a ready-to-send appeal letter you can take straight to your insurer.

Medical Bill Decoder

Paste your bill. It extracts every charge, flags suspicious or duplicate items, explains what each line means, and tells you your rights as a patient.

Document Decoder

Paste any medical document — lab results, referral letters, visit notes. Every medical term gets explained in plain language. Follow-up actions are laid out clearly.

Drug Checker

Enter any drug name. Get the drug class, generic alternatives, common side effects, safety warnings, and a list of questions to bring to your doctor.

Appointment Preparation

Going to the doctor? Describe what you want to discuss. HealthAdvocate generates talking points, questions to ask, and an advocacy script so you walk in prepared.

Discharge Translator

Discharge instructions are notoriously hard to follow. Paste them and get a clear medication schedule, warning signs to watch for, and follow-up steps — all in plain language.

Second Opinion Brief

Preparing for a second opinion? Paste your medical records and HealthAdvocate creates a structured, de-identified brief with key questions and records to bring.

Community Health Scanner

Saw a health claim online? Paste it. HealthAdvocate evaluates credibility, provides scientific context, and tells you whether to act or ignore it.

Family Health Tracker

Manage health profiles for your whole family — conditions, medications, allergies. This context flows into every other feature, so Drug Checker knows about interactions and Appointment Prep knows your history.

Health Tracks

Track ongoing health concerns over time with status updates and notes. See what's active, what's being monitored, and what you've resolved.

---

How It Works

HealthAdvocate uses a dual-layer AI architecture where two independent systems verify each other:

  Your input
      |
      v
  [OpenMed NER] ── Extracts diseases, drugs, anatomy, PII with confidence scores
      |
      v
  [PII Deidentification] ── Masks all personal data (names, SSN, dates, addresses)
      |
      v
  [Local LLM] ── Generates structured clinical assessment (runs on your machine)
      |
      v
  [Cross-Validation] ── Compares NER findings vs LLM reasoning
      |                    Flags disagreements, scores reliability
      v
  Your result

Layer 1 — OpenMed NER: Extracts medical entities from your text using state-of-the-art transformer models. Identifies diseases, medications, anatomical terms, and personally identifiable information with confidence scores.

Layer 2 — Local LLM: Generates a structured assessment — urgency level, action items, red flags, and plain-language explanations. Runs entirely on your machine via LM Studio.

Cross-validation: Every result goes through a reliability check. If NER finds a high-urgency entity (like "chest pain" at 90%+ confidence) but the LLM rates urgency as "low", the system overrides to "high". Safety first, always.

PII protection: Before any text reaches the LLM, all personal identifiers are stripped. Names become [first_name] [last_name], dates become [date], SSNs become [ssn]. The pii_scrubbed flag in every response confirms this happened.

---

Quick Start

What you need

• Python 3.10+
• LM Studio — free app to run LLMs locally. Download a medical model like Meditron3-8B.
• OpenMed — medical NLP toolkit (installed automatically)

Install

git clone https://github.com/simongonzalezdc/healthadvocate.git
cd healthadvocate
pip install -r healthadvocate/requirements.txt
pip install openmed[hf]

Run

1. Open LM Studio, load a medical model, start the local server (default port 1234)

2. Start HealthAdvocate:

export LM_STUDIO_URL=http://localhost:1234/v1
uvicorn healthadvocate.app:app --host 127.0.0.1 --port 8080

3. Open http://localhost:8080 in your browser

That's it. No sign-up, no API keys, no cloud.

CLI, MCP, and Agent Skill

HealthAdvocate also exposes safety-bounded agent surfaces for local preparation workflows:

python -m healthadvocate.cli brief
python -m healthadvocate.cli visit-questions --concern "persistent dizziness"
python -m healthadvocate.cli denial-checklist --denial-reason "not medically necessary"
python -m healthadvocate.cli server-health --url http://127.0.0.1:8080
python -m healthadvocate.mcp_server

• CLI: python -m healthadvocate.cli prepares visit questions, denial checklists, and server health checks.
• MCP: python -m healthadvocate.mcp_server starts a stdio MCP server for compatible agent hosts.
• Skill: skills/healthadvocate/SKILL.md tells agents how to help patients prepare without diagnosing or replacing professional care.

Example MCP config:

{
  "mcpServers": {
    "healthadvocate": {
      "command": "python",
      "args": ["-m", "healthadvocate.mcp_server"]
    }
  }
}

Configuration

---

API Reference

All endpoints accept and return JSON. Perfect for building integrations, bots, or custom frontends.

Core Features

# Symptom check
curl -X POST http://localhost:8080/api/symptoms/assess \
  -H "Content-Type: application/json" \
  -d '{"symptoms": "persistent headache and dizziness for a week"}'

# Decode a medical bill
curl -X POST http://localhost:8080/api/bills/decode \
  -H "Content-Type: application/json" \
  -d '{"bill_text": "ER Visit: EKG $450, Blood Work $125, X-Ray $275"}'

# Fight an insurance denial
curl -X POST http://localhost:8080/api/insurance/fight \
  -H "Content-Type: application/json" \
  -d '{"denial_text": "Your claim for MRI has been denied..."}'

# Check a drug
curl -X POST http://localhost:8080/api/drugs/check \
  -H "Content-Type: application/json" \
  -d '{"drug_name": "metformin"}'

All Endpoints

Response Format

Every feature endpoint returns a consistent structure:

{
  "explanation": "Plain-language summary written for the patient",
  "urgency": "high",
  "action_items": ["Call your doctor within 24 hours", "..."],
  "red_flags": ["Seek emergency care immediately if..."],
  "pii_scrubbed": true,
  "validation": {
    "confirmed": ["headache", "dizziness"],
    "ner_only": [],
    "llm_only": ["possible migraine"],
    "reliability": "high",
    "urgency_disagreement": false
  }
}

Module-specific fields (like suspicious_charges, draft_appeal, medication_instructions) are included alongside these common fields.

---

Privacy & Security

HealthAdvocate is designed as a privacy-preserving local-first health tool:

• All processing is local by default. No data is sent to a hosted HealthAdvocate service. The NER models run on your machine via HuggingFace. The LLM runs on your machine via LM Studio.
• PII is stripped before reasoning. Every patient-facing module deidentifies your text before it reaches the LLM. Names, dates, SSNs, phone numbers, emails, and addresses are masked using OpenMed's privacy-preserving PII detection.
• No persistent storage. Family profiles and health tracks are kept in memory only. When you stop the server, the data is gone. No database, no files, no data to breach.
• Zero telemetry. No analytics, no tracking pixels, no error reporting to external services. We wouldn't know how to find your data even if we wanted to.
• Local network only by default. The documented run command binds to 127.0.0.1, and browser CORS defaults to localhost. If you expose the app on a network or public URL, add authentication and a tighter deployment review first.

---

Accessibility

The UI uses accessibility-minded patterns because health tools should work for everyone:

• Skip-to-content link as the first focusable element
• aria-live regions on all result containers for screen reader announcements
• Screen-reader-only labels on every form input
• :focus-visible styles for keyboard navigation
• prefers-reduced-motion media query support
• Color choices are selected for readable contrast in light and dark themes
• role="img" on all decorative SVGs
• Semantic HTML throughout (<main>, <nav>, <header>, <footer>)

---

Tech Stack

---

Project Structure

healthadvocate/
  app.py                  FastAPI app, 17+ endpoints, request validation
  requirements.txt        Python dependencies (fastapi, openai, openmed)
  static/
    index.html            SPA with accessibility-minded markup
    styles.css            Humanistic design system (light + dark themes)
    app.js                Frontend logic with loading states and XSS protection
  core/
    engine.py             OpenMed model management, PII deidentification
    llm_client.py         LM Studio client with multi-strategy JSON parsing
    cross_validation.py   NER vs LLM reliability scoring
    symptom_assessor.py   Symptom assessment with urgency cross-check
    document_decoder.py   Medical document plain-language decoder
    bill_decoder.py       Bill analysis with price extraction and context
    insurance_fighter.py  Denial analysis and appeal letter generator
    drug_checker.py       Drug information with interaction checking
    appointment_prep.py   Doctor visit preparation with advocacy scripts
    discharge_translator.py  Discharge instruction plain-language translator
    second_opinion.py     Second opinion brief with de-identification
    community_health.py   Health bulletin credibility scanner
    family_tracker.py     Family health profile management
    health_tracks.py      Health concern tracking over time

---

Known Limitations

• In-memory storage: Family profiles and health tracks live in memory and are lost on server restart. This is intentional — no persistent data means no data to breach.
• Requires LM Studio: You need LM Studio running with a loaded model. Without it, feature endpoints return errors.
• LLM output quality: Results depend on the model you choose. Meditron3-8B is a strong medical model, but no LLM is a substitute for a real doctor.

---

Credits

HealthAdvocate is built on outstanding open-source work:

• OpenMed by Maziyar Panahi — Apache 2.0 licensed medical NLP toolkit. Powers the NER entity extraction, PII detection, and deidentification layers. [Paper]
• Meditron3-8B by the EPFL LLM Team — open-weight clinical reasoning model. Powers the structured assessment layer.
• LM Studio — free local LLM runtime with an OpenAI-compatible API.
• FastAPI by Sebastian Ramirez — high-performance async Python web framework.
• HuggingFace Transformers — the model inference backend behind OpenMed's NER pipelines.

Citing OpenMed

If you reference this project in academic work, please cite OpenMed:

@misc{panahi2025openmedneropensourcedomainadapted,
      title={OpenMed NER: Open-Source, Domain-Adapted State-of-the-Art Transformers for Biomedical NER Across 12 Public Datasets},
      author={Maziyar Panahi},
      year={2025},
      eprint={2508.01630},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2508.01630},
}

---

Links

• KyaniteLabs: kyanitelabs.tech
• AI / agent navigation: llms.txt
• Sibling projects: Print-OS · GameStory-Lab · voice-to-sculpture-app · CyberWitches · grocery-flywheel

---

License

This project is licensed under the Apache License 2.0.

OpenMed is a separate project by Maziyar Panahi, used here as a dependency under its own Apache 2.0 license.

What is HealthAdvocate?

HealthAdvocate is a health advocacy and patient-navigation tooling that helps people navigating healthcare systems and builders of advocacy tools advocate and navigate health workflows with structured support.

Who it's for

• Primary: people navigating healthcare systems and builders of advocacy tools
• Use when you need to advocate and navigate health workflows with structured support
• Skip if you need a medical device or clinical diagnosis product

FAQ

What is HealthAdvocate?

HealthAdvocate is a health advocacy and patient-navigation tooling. It helps people navigating healthcare systems and builders of advocacy tools advocate and navigate health workflows with structured support.

Who should use HealthAdvocate?

people navigating healthcare systems and builders of advocacy tools.

How is HealthAdvocate different?

Advocacy/navigation tooling — not a clinic or diagnostic device.

Is HealthAdvocate production software?

Treat the README status and release tags as source of truth for maturity. Validate against your own requirements before production use.

Status

• Maintained as of 2026 on the default branch
• Prefer release tags when pinning dependencies
• Report issues on the canonical remote listed above

Agent surface

• Coding agents: read this README first, then repo docs/AGENTS.md if present
• Prefer machine-readable briefs (llms.txt) when the repo ships one
• MCP or skill entrypoints are documented in-repo when applicable

Contributing

Issues and PRs welcome on the canonical remote. Keep public docs free of secrets and machine-local paths.

License

See LICENSE in this repository (or package metadata if license is package-only).