Metadata-Version: 2.4
Name: medcheck
Version: 0.1.0
Summary: AI-powered medical imaging analysis toolkit
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pycryptodome>=3.20.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pydicom>=3.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: reportlab>=4.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.15.0
Requires-Dist: uvicorn[standard]>=0.32.0
Provides-Extra: dev
Requires-Dist: bandit>=1.8.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: local-models
Requires-Dist: torch>=2.5.0; extra == 'local-models'
Requires-Dist: torchvision>=0.20.0; extra == 'local-models'
Description-Content-Type: text/markdown

<div align="center">

# MedCheck

**AI-powered medical imaging analysis toolkit**

[![CI](https://github.com/Liohtml/MedCheck/actions/workflows/ci.yml/badge.svg)](https://github.com/Liohtml/MedCheck/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/Liohtml/MedCheck/branch/main/graph/badge.svg)](https://codecov.io/gh/Liohtml/MedCheck)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![GitHub release](https://img.shields.io/github/v/release/Liohtml/MedCheck)](https://github.com/Liohtml/MedCheck/releases)
[![GitHub stars](https://img.shields.io/github/stars/Liohtml/MedCheck)](https://github.com/Liohtml/MedCheck/stargazers)

</div>

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](#quick-start)** · **[Documentation](docs/)** · **[Contributing](CONTRIBUTING.md)** · **[Report Bug](https://github.com/Liohtml/MedCheck/issues/new?template=bug_report.md)**

---

## 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.7, 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)

```bash
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](http://localhost:8080).

### Option 2 — pip install

```bash
pip install medcheck
medcheck serve
```

### Option 3 — From source

```bash
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 API, 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.7** | 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 |

---

## Data Sources

| Source | Type | Notes |
|---|---|---|
| **Local DICOM** | `file://` | Supports single files and directory trees |
| **easyRadiology** | REST API | Requires `EASYRAD_API_KEY` |
| **Custom providers** | Plugin | See [docs/providers.md](docs/providers.md) |

---

## Configuration

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

```bash
cp .env.example .env
```

```dotenv
# .env.example
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GOOGLE_API_KEY=
EASYRAD_API_KEY=

# Optional overrides
MEDCHECK_DEFAULT_MODEL=claude-opus-4-7
MEDCHECK_REPORT_FORMAT=pdf
MEDCHECK_PORT=8080
```

### Docker environment variables

```bash
docker run \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e MEDCHECK_DEFAULT_MODEL=claude-opus-4-7 \
  -e MEDCHECK_REPORT_FORMAT=pdf \
  ghcr.io/liohtml/medcheck:latest
```

---

## Custom Workflows

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

```yaml
# workflows/brain-mri-full.yml
name: brain-mri-full
description: Full brain MRI analysis with FLAIR and T1 sequences

steps:
  - name: preprocess
    op: normalize
    params:
      modality: MRI
      sequences: [FLAIR, T1]

  - name: segment
    op: local_model
    params:
      model: monai-brain-seg-v2

  - name: analyze
    op: vision_llm
    params:
      model: claude-opus-4-7
      prompt_template: prompts/neuro-radiology.txt

  - name: report
    op: render_report
    params:
      format: [pdf, html]
      include_annotations: true
```

Run the workflow:

```bash
medcheck run workflows/brain-mri-full.yml --input /data/scans/patient_001/
```

---

## Documentation

| Topic | Link |
|---|---|
| Quickstart guide | [docs/quickstart.md](docs/quickstart.md) |
| Data providers & plugins | [docs/providers.md](docs/providers.md) |
| Workflow engine reference | [docs/workflows.md](docs/workflows.md) |
| Supported models | [docs/models.md](docs/models.md) |

---

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

```bash
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](https://stanfordmlgroup.github.io/competitions/mrnet/) — benchmark dataset for knee MRI analysis
- [Project MONAI](https://monai.io/) — PyTorch-based framework for medical image learning
- [pydicom](https://pydicom.github.io/) — 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, or otherwise). It is intended solely as a research and educational tool. 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.**

---

## License

Distributed under the [Apache License 2.0](LICENSE).
