Metadata-Version: 2.5
Name: medmlx
Version: 0.8.0
Summary: MedMLX Python API, CLI, and MCP for independent medical imaging runtimes
Author: Joseph Sandoval, Alfredo Sandoval Jr.
License-Expression: Apache-2.0
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Classifier: Operating System :: MacOS :: MacOS X
Requires-Python: <3.14,>=3.13
Requires-Dist: medmlx-core<0.3,>=0.2.6
Requires-Dist: packaging>=24
Requires-Dist: psutil<8,>=7
Requires-Dist: uv<1,>=0.8
Provides-Extra: all
Requires-Dist: biomedparse-mlx<0.2,>=0.1.5; extra == 'all'
Requires-Dist: fdg-pet-ct-mlx<0.4,>=0.3.0; extra == 'all'
Requires-Dist: flexible-unet-mlx<0.3,>=0.2.6; extra == 'all'
Requires-Dist: flexray-mlx<0.3,>=0.2.6; extra == 'all'
Requires-Dist: lesiondiffusion-mlx<0.3,>=0.2.7; extra == 'all'
Requires-Dist: lung-nodule-mlx<0.3,>=0.2.6; extra == 'all'
Requires-Dist: medsam2-mlx<0.4,>=0.3.0; extra == 'all'
Requires-Dist: mlx-generate-ctmr<0.7,>=0.6.0; extra == 'all'
Requires-Dist: mlx-reason-ct[tools]<0.7,>=0.6.0; extra == 'all'
Requires-Dist: mlx-segment-ct<0.4,>=0.3.5; extra == 'all'
Requires-Dist: mlxradiomics<1.1,>=1.0.0; extra == 'all'
Requires-Dist: nibabel<6,>=5.4.2; extra == 'all'
Requires-Dist: nnunet-mlx<0.9,>=0.8.0; extra == 'all'
Requires-Dist: numpy<3,>=2.3; extra == 'all'
Requires-Dist: pillow<14,>=13; extra == 'all'
Requires-Dist: pydantic<3,>=2.14; extra == 'all'
Requires-Dist: radimagenet-mlx<0.4,>=0.3.3; extra == 'all'
Requires-Dist: sam3-mlx[video]<0.4,>=0.3.0; extra == 'all'
Requires-Dist: scipy<2,>=1.18; extra == 'all'
Requires-Dist: segresnet-mlx<0.4,>=0.3.3; extra == 'all'
Requires-Dist: simpleitk<3,>=2.5; extra == 'all'
Requires-Dist: swin-unetr-mlx<0.3,>=0.2.6; extra == 'all'
Requires-Dist: synthseg-mlx<0.4,>=0.3.4; extra == 'all'
Requires-Dist: totalsegmentator-mlx<0.3,>=0.2.0; extra == 'all'
Requires-Dist: unest-mlx<0.3,>=0.2.7; extra == 'all'
Provides-Extra: dicom
Requires-Dist: simpleitk<3,>=2.5; extra == 'dicom'
Provides-Extra: generate
Requires-Dist: fdg-pet-ct-mlx<0.4,>=0.3.0; extra == 'generate'
Requires-Dist: lesiondiffusion-mlx<0.3,>=0.2.7; extra == 'generate'
Requires-Dist: mlx-generate-ctmr<0.7,>=0.6.0; extra == 'generate'
Requires-Dist: mlx-reason-ct<0.7,>=0.6.0; extra == 'generate'
Requires-Dist: nibabel<6,>=5.4.2; extra == 'generate'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.2; extra == 'mcp'
Provides-Extra: reason-tools
Requires-Dist: lung-nodule-mlx<0.3,>=0.2.6; extra == 'reason-tools'
Requires-Dist: medsam2-mlx<0.4,>=0.3.0; extra == 'reason-tools'
Requires-Dist: mlx-reason-ct[tools]<0.7,>=0.6.0; extra == 'reason-tools'
Requires-Dist: nibabel<6,>=5.4.2; extra == 'reason-tools'
Requires-Dist: numpy<3,>=2.3; extra == 'reason-tools'
Requires-Dist: pillow<14,>=13; extra == 'reason-tools'
Requires-Dist: pydantic<3,>=2.14; extra == 'reason-tools'
Requires-Dist: scipy<2,>=1.18; extra == 'reason-tools'
Provides-Extra: segment
Requires-Dist: biomedparse-mlx<0.2,>=0.1.5; extra == 'segment'
Requires-Dist: flexible-unet-mlx<0.3,>=0.2.6; extra == 'segment'
Requires-Dist: flexray-mlx<0.3,>=0.2.6; extra == 'segment'
Requires-Dist: medsam2-mlx<0.4,>=0.3.0; extra == 'segment'
Requires-Dist: mlx-segment-ct<0.4,>=0.3.5; extra == 'segment'
Requires-Dist: nnunet-mlx<0.9,>=0.8.0; extra == 'segment'
Requires-Dist: sam3-mlx[video]<0.4,>=0.3.0; extra == 'segment'
Requires-Dist: segresnet-mlx<0.4,>=0.3.3; extra == 'segment'
Requires-Dist: swin-unetr-mlx<0.3,>=0.2.6; extra == 'segment'
Requires-Dist: synthseg-mlx<0.4,>=0.3.4; extra == 'segment'
Requires-Dist: totalsegmentator-mlx<0.3,>=0.2.0; extra == 'segment'
Requires-Dist: unest-mlx<0.3,>=0.2.7; extra == 'segment'
Provides-Extra: setup
Provides-Extra: vision
Requires-Dist: lung-nodule-mlx<0.3,>=0.2.6; extra == 'vision'
Requires-Dist: mlxradiomics<1.1,>=1.0.0; extra == 'vision'
Requires-Dist: radimagenet-mlx<0.4,>=0.3.3; extra == 'vision'
Description-Content-Type: text/markdown

<div align="center">

# MedMLX

One Python API, command line and MCP server for native medical imaging on Apple Silicon.
Run TotalSegmentator, nnU-Net, MedSAM2, SynthSeg and more through their independent MLX runtimes.

[![PyPI](https://img.shields.io/pypi/v/medmlx)](https://pypi.org/project/medmlx/)
[![Python](https://img.shields.io/badge/python-3.13-blue)](https://pypi.org/project/medmlx/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/MedMLX/medmlx/blob/main/LICENSE)
[![Apple Silicon](https://img.shields.io/badge/Apple_Silicon-MLX-black?logo=apple)](https://github.com/ml-explore/mlx)
[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97_Hugging_Face-weights-yellow)](https://huggingface.co/MedMLX)
[![MCP](https://img.shields.io/badge/MCP-server-A51C30)](https://github.com/MedMLX/medmlx/blob/main/docs/mcp.md)

[Models](#models) · [Setup guide](https://github.com/MedMLX/medmlx/blob/main/docs/setup.md) · [MCP guide](https://github.com/MedMLX/medmlx/blob/main/docs/mcp.md) · [Website](https://medmlx.org)

<img src="https://raw.githubusercontent.com/MedMLX/medmlx/main/docs/gallery.jpg" alt="Outputs across CT, PET/CT, radiographs, endoscopy and MRI" width="100%">

**Apple Silicon · Metal · Python 3.13** · [uv](https://docs.astral.sh/uv/)

</div>

## Install

```sh
uv tool install --python 3.13 "medmlx[all,mcp]"
```

For a Python project, use `uv add "medmlx[all,mcp]"`. Run `uv tool upgrade medmlx` to
update MedMLX and its models. Model weights download on first use and keep their own
terms. For a smaller install, replace `all` with one group:

| Extra | Installs |
| :--- | :--- |
| `all` | Every model runtime, with Reason-CT tools |
| `segment` | Segmentation runtimes, including SAM 3 video |
| `generate` | Reason-CT, NV-Generate, LesionDiffusion and FDG PET synthesis |
| `vision` | Lung nodule detection, RadImageNet features and radiomics |
| `mcp` | The MCP server |

## Quickstart

`medmlx models` lists the installed models. To segment a CT scan, put it in a
working folder and run from there:

```sh
mkdir -p ~/medmlx-work && cd ~/medmlx-work
cp /path/to/ct.nii.gz .
```

Then show the model's arguments, check that it can run, and run it:

```sh
medmlx describe mlx-segment-ct
medmlx readiness mlx-segment-ct --arg image_path=ct.nii.gz output_dir=segment-ct
medmlx run mlx-segment-ct --arg image_path=ct.nii.gz output_dir=segment-ct
```

- `--arg` takes the argument names `describe` lists. Values are converted to the
  declared types; give lists and other JSON values as `KEY:=JSON`, for example
  `points:='[[120, 140, 60]]'`. `--arguments FILE` reads them from a JSON file.
- Relative paths resolve against the current folder, or against `--root`.
- `readiness` checks Metal and the input paths without downloading anything.
- The first run downloads the `MedMLX/vista3d-ct-mlx` weights; later runs reuse the
  cache.
- The mask is written to `segment-ct/mlx_segment_ct_mask.nii.gz`.
- `medmlx setup --all --progress` downloads every model's weights for offline use. See
  [automatic weights and readiness](https://github.com/MedMLX/medmlx/blob/main/docs/setup.md).

## Models

Model IDs are what `medmlx run` and `medmlx describe` take.

| Model ID | Task | Input | Extra |
| :--- | :--- | :--- | :--- |
| `totalsegmentator` | Whole-body CT segmentation | CT | segment |
| `mlx-segment-ct`, `mlx-segment-ctmr` | Automatic and point-prompted segmentation (VISTA-3D) | CT, MRI | segment |
| `nnunet-liver`, `nnunet-pancreas`, `nnunet-autopet`, `nnunet-brats2021` | Organ and tumor segmentation (nnU-Net v2) | CT, PET/CT, brain MRI | segment |
| `mrsegmentator` | Multi-organ MRI segmentation | MRI | segment |
| `siam` | Whole-head segmentation from any MRI contrast or CT | Head MRI, CT | segment |
| `synthseg` | Brain segmentation and parcellation | Brain MRI, CT | segment |
| `medsam2` | Box-, point- or mask-prompted masks with propagation | NIfTI slices or volumes, frames | segment |
| `sam3` | Text-, box- or point-prompted image segmentation | 2D images, video frames | segment |
| `biomedparse-v2` | Text-prompted segmentation | 3D volumes, 2D images | segment |
| `swin-unetr` | 13 abdominal organs | Contrast CT | segment |
| `segresnet-brats`, `segresnet-renal-cect` | Brain tumor and renal structures | Brain MRI, multiphase CT | segment |
| `unest` | Kidney cortex, medulla and collecting system | CT | segment |
| `flexray` | Radiograph anatomy | Radiographs | segment |
| `flexible-unet` | Surgical tools | Endoscopy frames | segment |
| `lung-nodule` | Lung nodule detection | Chest CT | vision |
| `radimagenet-*` | Radiology image features | 2D images | vision |
| `mlx-reason-ct` | CT reports and question answering | CT | generate |
| `reason-ct-tools` | Reason-CT with nodule detection and MedSAM2 masks | Chest CT | reason-tools |
| `mlx-generate-ctmr-ct`, `-mr`, `-mr-brain` | Synthetic CT and MRI | Label maps or anatomy | generate |
| `lesiondiffusion` | Synthetic CT lesions | CT and organ mask | generate |
| `fdg-pet-ct` | Synthetic FDG PET (weight-free) | CT and labels | generate |
| `medgemma` | Image-to-text through a separate environment | 2D images | [bridge](https://github.com/MedMLX/medmlx/blob/main/docs/medvlm-bridge.md) |

Each model has its own repository in the [MedMLX organization](https://github.com/MedMLX).
`medgemma` and `mrsegmentator` require local weights.

### Memory

MedMLX runs one model at a time by default. It never refuses a run for memory:
readiness reports a model's peak next to the memory available, and the run starts
either way, so a Mac with too little memory may swap or fail. Declared peaks:

| Model | Peak MLX memory |
| :--- | ---: |
| `siam` | 16 GB |
| `nnunet-pancreas` | 14.5 GB |
| `mlx-reason-ct` | 12.5 GB |
| `synthseg` | 11.6 GB |
| `mlx-generate-ctmr-ct` | 11.1 GB |
| `mlx-segment-ctmr` | 11.0 GB |
| `lung-nodule` | 10.8 GB |
| `mlx-generate-ctmr-mr`, `mlx-generate-ctmr-mr-brain` | 10.2 GB |
| `nnunet-liver` | 9.0 GB |
| `swin-unetr`, `nnunet-brats2021` | 7.5 GB |
| `unest` | 7.3 GB |
| `mlx-segment-ct` | 6.0 GB |
| `sam3` | 5.4 GB |
| `totalsegmentator`, `segresnet-brats` | 5.0 GB |
| `nnunet-autopet` | 4.8 GB |
| `segresnet-renal-cect` | 4.1 GB |
| `biomedparse-v2` | 3.9 GB |
| `lesiondiffusion` | 3.5 GB |
| `fdg-pet-ct` | 2.8 GB |
| `medsam2` | 1.3 GB |
| `flexray` | 1.2 GB |
| `radimagenet-*`, `flexible-unet` | 0.5 GB or less |

Models without a declared peak, such as `mrsegmentator`, record their measured peak
after each run, and `medmlx describe` reports it.

`medgemma` runs in its own interpreter, outside this check. Describing a chest
radiograph peaks at 4.4 GB with MedGemma 1.5 4B and 17.9 GB with MedGemma 27B.

## MCP

`medmlx serve --root /path/to/work` runs a stdio MCP server that lets an
assistant list models, check inputs and run jobs in that folder. For Claude Code:

```sh
mkdir -p ~/medmlx-work
claude mcp add --scope user medmlx -- "$(uv tool dir --bin)/medmlx" serve --root "$HOME/medmlx-work"
```

For clients configured with JSON, use absolute paths:

```json
{
  "mcpServers": {
    "medmlx": {
      "command": "/absolute/path/to/medmlx",
      "args": ["serve", "--root", "/absolute/path/to/medmlx-work"]
    }
  }
}
```

Disconnecting the client cancels its running jobs. The
[MCP guide](https://github.com/MedMLX/medmlx/blob/main/docs/mcp.md) covers Codex,
other clients, tools and a complete job workflow.

## Python

```python
import medmlx

result = medmlx.run(
    "mlx-segment-ct",
    arguments={"image_path": "ct.nii.gz", "output_dir": "segment-ct"},
    root="/path/to/medmlx-work",
)
```

For a model declaring a `cohort` adapter, queue up to 256 cases with one prepared
model. The liver adapter supports this explicitly:

```python
with medmlx.start_cohort(
    "nnunet-liver",
    preparation={"weights_path": "liver-model"},
    cases=[
        {"image_path": "ct-a.nii.gz", "output_dir": "out-a"},
        {"image_path": "ct-b.nii.gz", "output_dir": "out-b"},
    ],
) as cohort:
    cases = cohort.wait()["result"]["cases"]
```

Cases run in order and report individual results or errors. Weights and model
configuration stay fixed until the cohort closes automatically after its final
case. Leaving the context early cancels the worker and its child processes.

## More

- [Reason-CT with nodule tools](https://github.com/MedMLX/medmlx/blob/main/docs/reason-ct-tools.md):
  detect and segment nodules, then browse masks and measurements in a local CT viewer.
- [MedGemma bridge](https://github.com/MedMLX/medmlx/blob/main/docs/medvlm-bridge.md):
  run MedGemma in a managed environment with local weights.
- This README describes the 0.4.7 release on [PyPI](https://pypi.org/project/medmlx/).
  Unreleased changes are in the [release notes](https://github.com/MedMLX/medmlx/blob/main/docs/release-notes.md);
  to use them, install from the locked source workspace described in the
  [MCP guide](https://github.com/MedMLX/medmlx/blob/main/docs/mcp.md).
- Development: [declaring models](https://github.com/MedMLX/medmlx/blob/main/docs/declaring-models.md),
  [checkpoint conversion](https://github.com/MedMLX/medmlx/blob/main/conversion/README.md)
  and the [shared core runtime](https://github.com/MedMLX/medmlx/blob/main/packages/core/docs/technical.md).

## License

[Apache-2.0](https://github.com/MedMLX/medmlx/blob/main/LICENSE). See [third-party notices](https://github.com/MedMLX/medmlx/blob/main/THIRD_PARTY_NOTICES.md).
Runtimes and model weights retain their own terms.
