GroundCheckHealth GitHub

Grounded answers, or none at all.

Open-source clinical AI that answers only from sources you trust, cites every claim, and refuses when it can’t back one up.

View source on GitHub Watch the demo

MIT licensed. Runs on your own machine in a few minutes — see Get started.

  • 0 of 222,210 must-refuse questions answered in testing
  • 11 checks on every question
  • Runs on a laptop, with optional local AI and no API key
Audit record 82f38f41 6 ms

“What is the recommended dose of Zalortin for a patient with Veltris syndrome?”

  1. PII redactionno personal data found<1
  2. Scope checkno injection patterns<1
  3. Rate limitwithin limit<1
  4. Retrievetop 4 passages, best score 0.715
  5. Retrieval gate0.71 clears the 0.30 threshold<1
  6. Source coverage“zalortin” is in no trusted source1
  7. Generatenot reached–
  8. Schema validationnot reached–
  9. Grounding checknot reached–
  10. Dosage guardnot reached–
Refused Routed for review. No model was called.
Real runs of the pipeline. Zalortin isn’t in any source, so the first stops before a model writes a word. The second passes every check and is shown with its citations.

See it in 50 seconds

A real screen recording of the app on a laptop, with synthetic data and no API key.

What happens in the video
  1. A question about Caloradine’s standard dose gets an answer in which every statement cites its source, shown with the retrieved passages and a trace of every check.
  2. A question about a 5-year-old is refused, because no trusted source covers children. The refusal appears in the Review queue for a clinician.
  3. The Usage page shows questions, refusal rates and response times.
  4. A classifier trained on public abdominal CT scans on the laptop’s GPU shows its training curves, then names the organ in a CT slice as liver.
  5. The app switches to dark mode, and the Data protection page verifies that the audit trail is intact and signed.

A system that knows when to stop is safer than one that always answers.

  • Code decides, not the model

    Plain, testable checks decide what’s shown, with or without AI.

  • Every claim is cited

    Each sentence points to the source passage it came from.

  • Every request is recorded

    A full trace is saved, whether it answered or refused.

Explore the dashboard

Unedited screenshots of the app in this repository, in light and dark mode, with synthetic data.

The GroundCheckHealth app: a sidebar of pages, and the Ask page with a question box and example questions that answer and refuse.
Ask a question. Type your own, or start from examples that answer and refuse.
An answer about Caloradine's standard dose, with each sentence followed by a source ID such as CALO-001, and a button to flag the answer for review.
Get a cited answer. Every statement is tagged with the source it came from.
A refused question about a 5-year-old. The reason says no trusted source covers children, and the pipeline trace shows the source coverage check failing.
See why it refused. A plain-language reason, and the exact check that stopped it.
A refused question about Caloradine for an 87-year-old taking Tessorin. Two checks are unsafe: the combination is contraindicated, and the creatinine clearance of 21.4 is below the limit.
Check it against the patient. Allergies, interactions and kidney function can stop an answer.
Retrieved source cards with IDs, sections and similarity scores, beside a pipeline trace with a status and timing for each stage.
Inspect the evidence. Retrieved passages with scores, next to every stage of the run.
The Review page: a queue of open cases, including a flagged answer and refusals, each with its type, how often it was asked, due date and assignee.
Review refusals and flags. Every refusal and flagged answer becomes a case with a due date.
The Usage page: tiles for questions, refusal rate, response time, model drafting, identifiers removed and open reviews, above a chart of questions per day.
See how it’s used. Questions, refusals, response times and what needs attention.
A finished training run for an abdominal CT organ classifier on the Apple GPU, with loss and accuracy charts over ten epochs.
Train on your own scans. Pick a folder and a GPU, then watch loss and accuracy live.
A model card for the abdominal CT organ classifier: a CT slice classified as liver, with 96.3% accuracy on 17,778 test images and per-class figures.
Use a trained model. Accuracy per class, and it abstains when unsure.
The CT and MRI page: an axial slice of a public abdominal CT in a dark viewer with orientation letters, the model abstaining because 78% of image regions were unlike its training images, and a signed report.
Read CT and MRI. De-identified series, a model that abstains, and a signed report.
A CDS Hooks request for Caloradine 15 mg and the cards returned: a critical card saying the dose is too high for an eGFR of 41, with the formulary rule and override reasons, and a warning about an interaction.
Check orders in the EHR. CDS Hooks cards with the rule behind them, when a medicine is ordered.
The Data protection page: the audit trail verified as intact and signed, AES-256-GCM encryption on, and retention periods set.
Protect the data. Verify the audit trail, with encryption and retention status.
The Evaluation page: 2,008 of 2,008 cases pass, a sample of cases, and 16 of 16 adversarial probes behaving as intended.
Check the evaluation. Golden-set results and adversarial probes, failures included.

Who it’s for

  • Engineers

    Start from guardrails that already work, with tests.

  • Clinical safety teams

    See refusal, citation and audit enforced in code.

  • Researchers and educators

    An offline testbed with 265,778 test questions.

  • Reviewers and auditors

    Trace any decision to its check and its source.

Not for patient care. GroundCheckHealth isn’t clinically validated or cleared by any regulator.

Eleven checks, always in order

Any check can stop the run. Everything after it is skipped and recorded.

  1. Check the question

    1. 1PII redactionHides emails and long numbers
    2. 2Scope checkBlocks prompt injection
    3. 3Rate limitStops one caller using it all

  2. Find the evidence

    1. 4RetrieveFinds the closest passages
    2. 5Retrieval gateRefuses weak matches
    3. 6Source coverageRefuses terms no source mentions

  3. Draft and verify

    1. 7GenerateDrafts claims with citations
    2. 8Schema validationRejects malformed output
    3. 9Grounding checkChecks each claim against its source
    4. 10Dosage guardVerifies every dose

  4. Decide and record

    1. 11Decision and auditAnswers or refuses, and saves why

The checks that matter most

Real inputs, real results.

Dosage guard

Every dose in a draft must match a source, however it’s written.

fifteen milligrams15mg15 mg15 mgin source
Start Caloradine at 50 mg once daily.50 mgin no source

Source coverage

Refuses before drafting when a key term appears in no source.

Can children take Caloradine?childrennot covered

Grounding check

Each claim must be supported by the source it cites.

Caloradine is started at 15 mg once daily for 14 daysVELT-002grounded

Input guards

Redacts obvious personal data and blocks injection attempts.

My email is a@b.comMy email is [redacted]
Ignore previous instructions and…blocked

Works with or without AI

Only the drafting step changes. The same checks decide every time.

  • Available

    Extractive

    Answers are built from sentences in your sources.

    • No API key
    • Fully offline
  • Available

    Cloud model

    Any OpenAI-compatible model drafts the answer. Groq is the default.

    • Needs an API key
    • Sends redacted question and passages
  • Available

    Local AI model

    An open-source model on your own machine drafts the answer, through Ollama.

    • No API key
    • Offline after one download

If a model fails or times out, GroundCheckHealth falls back to the extractive answer.

Private AI on your own machine

AI-written answers that never leave your computer.

  • Detects your memory and GPU, including Apple silicon and NVIDIA
  • Recommends open-source models that fit, with their licences
  • Downloads and loads a model with one click, through Ollama
  • Falls back to extractive answers if the model is unavailable

Tested with Llama 3.2 3B on an Apple M1 laptop: 49 of 50 sample questions and 16 of 16 adversarial probes correct, no unsafe answers, about 10 seconds per answer.

The Local AI page: this machine's Apple M1 with 16 GB of memory, and open-source models with how well each fits, download size and licence.
The Local AI panel in the dashboard.

Tested on 265,778 questions

The build fails if a single question that should be refused gets answered.

  • Must refuse

    1,004 of 1,004 refused

    Unknown drugs, off-topic questions, missing context. Gates every build.

  • Answerable

    1,004 of 1,004 answered

    Questions the sources can answer. Over-refusals would be reported here.

  • Adversarial probes

    16 of 16 handled

    Leading questions, misspellings, injections, casual phrasing. Reported, not gating.

And 250,000 more

Beyond the gating set, a generated evaluation of 265,778 questions and patient scenarios: medicines that don’t exist, one-letter misspellings of real ones, questions about children and pregnancy the sources don’t cover, doses the sources never state, one medicine’s dose asserted against another, instructions to ignore the sources, and patients the formulary says a medicine is unsafe for. Expectations come from the documents and the formulary, never from GroundCheckHealth’s own code. A sample runs on every push and the whole set weekly. In the latest run, all 222,210 questions that had to be refused were refused.

The other direction is measured too, because it is the one a clinician feels: 12,056 answerable questions asked the way a person asks them — “remind me”, “a colleague asked”, “what’s the duration”, “for a 40 year old” — with none refused. A separate run puts 1,215 deliberately wrong claims to the grounding and dosage checks, which the big evaluation cannot do, because its answers are quoted from the sources and so are true by construction. None of the wrong doses were accepted.

Runs offline in extractive mode, so these results measure the checks, not a language model.

1,880 documents, none of them real

Structured like MedQuAD and DailyMed drug labels. Every drug and dose is invented, so it’s safe to share and fork.

Conditions906
Drug labels752
Lab markers120
Procedures100
Reference notes2
The 3D map of passage embeddings, coloured by document type, with the sources retrieved for a question labelled.
The corpus map in the dashboard. Retrieved sources are labelled.

One JSON API

Call it from your own app, a batch job or a test suite.

Request
curl -X POST http://localhost:8000/api/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the recommended dose of Zalortin?"}'
Response, trimmed
{
  "decision": "refuse",
  "refused_reason": "the term 'zalortin' does not appear in any trusted source",
  "claims": [],
  "sources": [{ "id": "VELT-002", "score": 0.71, … }],
  "trace": [
    { "name": "retrieval gate", "status": "pass", "detail": "best score 0.71 clears threshold 0.30" },
    { "name": "source coverage", "status": "fail", "detail": "the term 'zalortin' does not appear in any trusted source" },
    { "name": "generate", "status": "skip", "detail": "not reached" },
    …
  ],
  "audit_id": "a83c1266",
  "llm_used": false
}

Send a settings object to override thresholds or switch individual guards for a single request. Configured defaults are never changed.

Endpoints

POST /api/ask
Run a question through the pipeline
GET /api/audit
Recent audit records
GET /api/audit/{id}
One full audit record
GET /api/settings
Default settings and their allowed ranges
GET /api/eval-summary
The latest evaluation results
GET /api/corpus
Corpus statistics and the 3D map
GET /api/health
Status, model mode and corpus size
POST /api/auth/login
Sign in, when accounts are required
GET /api/local-ai
Hardware, Ollama status and model fit

Built with

  • FastAPI
  • Pydantic
  • sentence-transformers
  • SQLAlchemy
  • Qdrant
  • Ollama
  • OpenAI client
  • Docker
  • Plain HTML, CSS, JS

Make it yours

Point it at your documents and run it on your own machines.

Use your own documents

Upload PDFs, Word files or web pages, approve them, and they’re searchable with citations.

curl -X POST http://localhost:8000/api/sources \
  -F file=@sepsis_protocol.pdf \
  -F owner=Pharmacy \
  -F expires_on=2027-09-30

Tune the thresholds

Every threshold is an environment variable.

RETRIEVAL_MIN_SCORE=0.30
GROUNDING_MIN=0.45
TOP_K=4
RATE_LIMIT_PER_MINUTE=30

Choose your model, or none

Any OpenAI-compatible API, or none at all.

GROQ_API_KEY=…
GROQ_BASE_URL=https://api.groq.com/openai/v1
GEN_MODEL=llama-3.3-70b-versatile
FORCE_EXTRACTIVE=false

Run it where your data lives

One container. In extractive mode, nothing leaves the machine.

docker build -t groundcheck .
docker run -p 7860:7860 groundcheck

Known limits

Each one is a good place to contribute.

  • Word-based coverage checkUnusual phrasing can still cause a refusal.
  • Rule-based de-identificationCatches common identifiers, not every way a person can be identified.
  • Synthetic tuningThresholds need re-tuning for real documents.
  • Self-referential testsAnswerable cases come from the corpus itself.
  • Text-layer documents onlyScanned PDFs need OCR before import.
  • Demonstration imaging modelsTrained on small public datasets, they abstain on most real scans.
  • Not a certified deviceSafety reports support your own clinical safety sign-off.

Where GroundCheckHealth is headed

From a reference pipeline to a platform hospitals can run safely. Planned work is built in the open.

  • Available now

    Grounded retrieval core

    Prove that a clinical assistant can refuse, cite and record by design.

    What’s included
    • Eleven-stage pipeline with deterministic guards
    • Citations, trace and audit record for every request
    • 2,008-case evaluation that gates the build, and 265,778 generated cases behind it
    • Tuning dashboard and JSON API
  • Available now

    Local AI models

    AI-written answers that never leave the machine.

    What’s included
    • Hardware check for memory, GPU and Apple silicon
    • Open-source models recommended to fit that hardware
    • One-click download and loading through a local runtime such as Ollama
    • Automatic fallback to extractive answers when no model is available
  • Available now

    Accounts and data foundation

    Every user, decision and passage in a durable, queryable home.

    What’s included
    • SQLite by default, PostgreSQL or MySQL in production, with automatic migrations
    • Pluggable vector store: exact local search, or Qdrant at scale
    • Sign-in with Argon2id-hashed passwords, lockout, and authenticator-app two-factor
    • Clinician, reviewer and admin roles, with every audit record tied to a user
  • Available now

    Your organisation’s knowledge

    Answer from a hospital’s own approved guidelines, formularies and protocols.

    What’s included
    • Import PDF, Word, HTML and Markdown, split into sections by their own headings
    • Owners, versions, and effective and expiry dates checked on every search
    • Approval by someone other than the uploader before anything is cited
    • Automatic re-indexing, and test questions generated from each document
  • Available now

    Clinician review and governance

    Turn every refusal and flagged answer into a reviewed, closed case.

    What’s included
    • A review queue for every refusal and flagged answer, with assignment, due dates and escalation
    • Resolved cases that become permanent test questions, so a mistake is caught from then on
    • A hazard log scored by severity and likelihood, before and after controls
    • Usage, refusal and review reports, and a safety case summary to download
  • Available now

    Security, privacy and access

    Meet hospital IT and information governance requirements.

    What’s included
    • Single sign-on with OpenID Connect (Entra ID, Okta, Keycloak and others), with roles from your identity provider
    • Names, dates, NHS numbers and contact details removed from questions before they’re stored or searched
    • AES-256 encryption of stored questions and answers, and a signed, tamper-evident audit trail
    • A hardened on-premises deployment with HTTPS, retention periods and a hardening checklist
  • Available now

    Patient-aware safety checks

    Check answers against the patient in front of the clinician, not just the literature.

    What’s included
    • Allergy, contraindication, drug-interaction and duplicate-class checks against a structured formulary
    • Doses adjusted for kidney function (eGFR or creatinine clearance), liver function and weight
    • Children, pregnancy, breastfeeding, lab results and high-alert medicines handled explicitly
    • Refusal when required patient data is missing, tested on 383 patient scenarios
  • Available now

    EHR integration

    Bring grounded answers into the clinical workflow, where decisions are made.

    What’s included
    • HL7 FHIR R4 access to labs, allergies, medications and conditions, without copying identifiers
    • SMART on FHIR launch from inside the electronic health record, with PKCE
    • CDS Hooks cards with cited rules when a medication is ordered, from signed EHR calls
    • Reviewed answers saved to the record as preliminary notes, tested live in the SMART sandbox
  • Available now

    CT and MRI imaging

    Apply the same principle to scans: show the evidence, or abstain.

    What’s included
    • DICOM upload, and PACS search and retrieval over DICOMweb, de-identified on import to the DICOM PS3.15 profile
    • A viewer with CT windows, standard orientation, and model regions slice by slice
    • Models that refuse the wrong modality and abstain on series unlike their training images
    • Clinician sign-off with amendments, exported as DICOM Structured Reports and sent back to the PACS
  • Available now

    Model training studio

    Train imaging models on your own images and hardware, and keep them in a library.

    What’s included
    • Choose a folder of PNG, JPEG or TIFF images arranged by class, with checks before training
    • Detects NVIDIA, AMD and Apple GPUs and lets you choose one, or the CPU
    • Live loss and accuracy, early stopping, and cancel at any time
    • A model library where every model abstains when unsure or shown an unfamiliar image
  • Available now

    Production operations

    Run across many sites, and catch problems before clinicians do.

    What’s included
    • Several hospitals or clinics in one installation, each seeing only its own records, on Docker Compose or Kubernetes with Helm
    • Prometheus metrics, health probes, and alerts on refusal rates, response times, drift from the documents and overdue reviews
    • Every change to the documents checked against the safety tests before it goes live, with one-step rollback
    • Incident reporting graded by harm, with regulator deadlines for data breaches and serious harm

Designed toward regulated use

GroundCheckHealth holds no certifications or clearances today. These are the standards it is being designed toward.

Privacy
HIPAA, GDPR, UK GDPR
Security
SOC 2 Type II, ISO/IEC 27001
Medical software
IEC 62304 lifecycle, ISO 14971 risk management, ISO 13485 quality management
Regulation
FDA software as a medical device pathways, EU MDR, EU AI Act high-risk requirements
Clinical safety
Clinical validation studies, and DCB0129 and DCB0160 for NHS deployments

Want to shape what comes first, or help build it? Join the discussion on GitHub.

Train models on your own scans

For teams without a machine learning platform. Try it on public CT scans with one command.

  1. Choose a folder of PNG, JPEG or TIFF images, one subfolder per class
  2. Pick a detected GPU, or train on the CPU
  3. Watch loss and accuracy live, and cancel at any time
  4. Get sensitivity, specificity, AUC and a confusion matrix for every class
  5. Abstain below a confidence threshold, and on unfamiliar images
  6. Save to a model library you can copy to another machine

Run a trained model over whole CT and MRI series on the CT and MRI page. NIfTI input and 3D models are planned.

Design sketch, not a screenshot. With several GPUs, you choose one.

Get started

Run it locally in a few minutes. Python 3.12, or Docker. The embedding model downloads once, the first time you build the index.

With Python

Terminal
git clone https://github.com/sumitgundawar/GroundCheck.git
cd GroundCheckHealth
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python scripts/build_index.py
uvicorn app.main:app --port 8000

Then open http://localhost:8000.

With Docker

Terminal
git clone https://github.com/sumitgundawar/GroundCheck.git
cd GroundCheckHealth
docker build -t groundcheck .
docker run -p 7860:7860 groundcheck

Then open http://localhost:7860. The image builds the index and runs the evaluation during the build. This run is for trying it out and keeps nothing; the on-premises guide covers an install that keeps its data.

Full setup, configuration and Windows instructions are in the README.

Questions

Not answered here? Ask on GitHub.

Is GroundCheckHealth a medical device?

No. It’s research and engineering software. It hasn’t been clinically validated or cleared by the FDA, a notified body or any other regulator, and it must not be used to make decisions about real patients.

Does my data leave my machine?

Not in extractive mode. Questions are processed locally, and the only download is the embedding model when the index is first built. In live model mode, the redacted question and retrieved passages are sent to the provider you configure, so choose that provider under your own data-protection rules.

Can I use it with real clinical documents?

Yes. Import your approved guidelines, formularies and protocols as PDF, Word, HTML or Markdown; someone other than the uploader approves each one, and every change is checked against the safety tests before it goes live. Re-tune the thresholds and add test questions for your content, because the defaults were tuned on synthetic data. Keep real patient data out of issues and pull requests.

Which language models work?

Any API compatible with OpenAI chat completions that supports JSON output mode, including servers you host yourself. Set GROQ_BASE_URL, GROQ_API_KEY and GEN_MODEL. The variable names mention Groq because it’s the default provider.

Can I use AI without sending data to the cloud?

Yes. Install Ollama, then open the Local AI panel in the dashboard. GroundCheckHealth recommends open-source models that fit your machine, downloads the one you choose, and runs it locally. Extractive mode is also fully local, without AI-written drafts.

Do I need a GPU?

No. Embeddings and vector search run on a CPU, and a laptop handles the demo corpus comfortably. Local AI models use a GPU when one is available, and smaller models run on a CPU.

Can I use it in a commercial product?

The MIT License allows commercial use, modification and redistribution. Making a clinical product out of it is your responsibility, including any regulatory approvals, validation and data-protection obligations.

Can I train models on my own images?

Yes. Choose a folder of images arranged by class, pick a GPU or the CPU, and watch it train. Each model is saved to a library with its accuracy per class, and it abstains when it isn’t confident or an image looks unfamiliar. To try it, python scripts/fetch_scan_dataset.py organamnist downloads public abdominal CT slices.

Can a hospital group run it?

Yes. One installation serves several hospitals or clinics: each site sees only its own questions, reviews, incidents and imaging, and group staff see all of them. It runs with Docker Compose and PostgreSQL, or on Kubernetes with the Helm chart, and exposes Prometheus metrics, health probes and alerts for your operations team.

Does it analyse CT or MRI scans yet?

Yes, as a research and evaluation workflow. Import DICOM series by upload or from a PACS, run a model trained in the studio over them, and sign a report that exports as a DICOM Structured Report. Models abstain on series unlike their training images: the demonstration CT model, trained on small public organ crops, abstains on real abdominal CT. No model here is validated for diagnosis. NIfTI input and 3D models are planned.

Help build safer clinical AI

Run it, break it, and tell us what it got wrong. Code, test cases and ideas are all welcome.

Star on GitHub Get started