medcheck 0.3.0

AI-powered medical imaging analysis toolkit

MedCheck

AI-powered medical imaging analysis toolkit

MedCheck analyzes MRI scans using local ML models and frontier Vision-LLMs (Claude, GPT, Gemini) to generate professional radiology-style reports with annotated images.

---

Quick Start · Documentation · Contributing · Report Bug

---

Features

• Plug & Play Docker — single docker run command, no local setup required
• Multiple data sources — local DICOM files, easyRadiology platform, and custom plugins
• Local ML analysis — on-device inference with LLaVA-Med and MONAI-based models; fully offline capable
• Vision-LLM analysis — frontier model support for Claude Opus 4.8, GPT-5.5, and Gemini 3.5 Flash
• Clinical context input — attach patient history, symptoms, and prior findings to guide report generation
• Professional PDF/HTML reports — annotated images with structured radiology-style findings and impressions
• YAML workflow engine — compose and version-control custom analysis pipelines as code
• Generic anatomy support — brain, spine, knee, shoulder, abdomen, and more
• Web UI + CLI — interactive browser dashboard and a scriptable command-line interface

---

Quick Start

Option 1 — Docker (recommended)

docker run -p 8080:8080 \
  -e ANTHROPIC_API_KEY=your_key_here \
  -v $(pwd)/scans:/data/scans \
  ghcr.io/liohtml/medcheck:latest

Then open http://localhost:8080.

Option 2 — pip install

pip install medcheck
medcheck serve

Option 3 — From source

git clone https://github.com/Liohtml/MedCheck.git
cd MedCheck
uv sync
uv run medcheck serve

---

How It Works

┌─────────┐    ┌────────────┐    ┌────────────┐    ┌───────────┐    ┌────────┐
│  Ingest  │───▶│ Preprocess │───▶│ ML Analyze │───▶│ Vision AI │───▶│ Report │
│          │    │            │    │            │    │           │    │        │
│ DICOM /  │    │ Normalize  │    │ LLaVA-Med  │    │ Claude /  │    │ PDF /  │
│ easyRad  │    │ Resize     │    │ MONAI      │    │ GPT /     │    │ HTML   │
│ Plugins  │    │ Anonymize  │    │ Anomaly    │    │ Gemini    │    │ + PNG  │
└─────────┘    └────────────┘    └────────────┘    └───────────┘    └────────┘

1. Ingest — load studies from local paths, the easyRadiology portal, or third-party plugins.
2. Preprocess — normalize pixel values, resize to model input dimensions, and strip PHI.
3. ML Analyze — run local segmentation and anomaly-detection models (no API key required).
4. Vision AI — send annotated slices to a frontier Vision-LLM for language-based findings.
5. Report — render a structured radiology report with annotated images in PDF and HTML.

---

Supported Models

Model	Provider	Best For
Claude Opus 4.8	Anthropic	Highest diagnostic quality and reasoning depth
GPT-5.5	OpenAI	High-resolution image understanding
Gemini 3.5 Flash	Google	Speed-optimized, cost-effective batch processing
LLaVA-Med	Local	Fully offline, no API key required (coming soon — #18)

---

Data Sources

Source	Type	Notes
Local DICOM	Folder / ZIP	Point to any directory or ZIP of DICOM files
easyRadiology	Portal link	Authenticates with the access code from your clinic (date of birth optional)
Custom providers	Plugin	See docs/providers.md

---

Configuration

Copy .env.example and fill in your API keys:

cp .env.example .env

# LLM API Keys (at least one needed for Vision analysis)
ANTHROPIC_API_KEY=        # https://console.anthropic.com/settings/keys
OPENAI_API_KEY=           # https://platform.openai.com/api-keys
GOOGLE_API_KEY=           # https://aistudio.google.com/apikey

# Defaults
MEDCHECK_LLM_PROVIDER=claude   # claude | openai | gemini
MEDCHECK_LANGUAGE=en           # en | de
MEDCHECK_HOST=127.0.0.1        # localhost only; set 0.0.0.0 to expose on the network
MEDCHECK_PORT=8080
MEDCHECK_API_KEY=              # when set, /api requires an X-API-Key header
MEDCHECK_RATE_LIMIT=10         # POST /api/analyze requests per IP per minute (0 = off)

Security: The server binds to 127.0.0.1 by default. If you expose it on the network (MEDCHECK_HOST=0.0.0.0), set MEDCHECK_API_KEY so the /api endpoints require an X-API-Key header — this app handles patient PHI.

Patient data & cloud LLMs: Vision analysis sends imaging data to an external LLM provider only after explicit consent. Pass --allow-cloud-llm, set MEDCHECK_ALLOW_EXTERNAL_LLM=1, or confirm the interactive prompt. If the requested provider is unavailable, MedCheck never reroutes data to a different cloud provider. See SECURITY.md.

Reports contain PHI: generated reports embed patient name, ID and birth date from the DICOM metadata. Pass --deidentify to replace them with a stable pseudonym. Report files are written with owner-only permissions.

Note: easyRadiology requires no API key. Authentication uses the access code provided by your radiology clinic (via SMS, email, or letter). A date of birth may be requested by the portal but is not verified by MedCheck.

Docker environment variables

docker run -p 8080:8080 \
  -e ANTHROPIC_API_KEY=sk-... \
  ghcr.io/liohtml/medcheck:lite

---

Custom Workflows

Define analysis pipelines as YAML and commit them alongside your code:

# workflows/full_analysis.yml
name: full_analysis
description: Complete MRI analysis with ML and Vision-LLM

steps:
  - ingest:
  - preprocess:
      normalize: true
      auto_detect_anatomy: true
  - ml_analysis:
      models: [anomaly_detection, feature_extraction]
  - vision_analysis:
      provider: claude
      clinical_context:
        symptoms: "Medial knee pain after sports injury"
        trauma: "Valgus stress, 10 days ago"
  - report:
      format: pdf
      language: en

Run a workflow:

medcheck analyze --source ./dicoms --workflow workflows/default.yml

Discover what's available:

medcheck providers   # list registered data providers
medcheck models      # list LLM providers, default models, and availability

---

Documentation

Topic	Link
Quickstart guide	docs/quickstart.md
Data providers & plugins	docs/providers.md
Workflow engine reference	docs/workflows.md
Supported models	docs/models.md
Intended use & positioning	docs/intended-use.md
Model card (limitations & risks)	docs/model-card.md

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md first.

git clone https://github.com/Liohtml/MedCheck.git
cd MedCheck
uv sync
pre-commit install
pytest

All pull requests require passing CI and at least one approving review.

---

Acknowledgments

MedCheck builds on the shoulders of excellent open-source work:

• Stanford MRNet — benchmark dataset for knee MRI analysis
• Project MONAI — PyTorch-based framework for medical image learning
• pydicom — pure-Python DICOM file I/O

---

Disclaimer

MedCheck is NOT a medical device and has NOT been cleared or approved by any regulatory authority (FDA, CE/EU MDR, or otherwise). It is intended solely as a research and educational tool. It must NOT be used to diagnose, screen for, or rule out any condition. All outputs must be reviewed and verified by a qualified radiologist or licensed medical professional before use in any clinical decision-making context. Do not use MedCheck as a substitute for professional medical advice, diagnosis, or treatment.

See Intended Use & Positioning for the scope and the do/don't boundary, and the Model Card for limitations and known risks.

---

License

Distributed under the Apache License 2.0.