Metadata-Version: 2.5
Name: medmlx
Version: 0.3.2
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.2.4
Requires-Dist: packaging>=24
Provides-Extra: all
Requires-Dist: biomedparse-mlx==0.1.2; extra == 'all'
Requires-Dist: fdg-pet-ct-mlx==0.2.2; extra == 'all'
Requires-Dist: flexible-unet-mlx==0.2.2; extra == 'all'
Requires-Dist: flexray-mlx==0.2.2; extra == 'all'
Requires-Dist: lesiondiffusion-mlx==0.2.2; extra == 'all'
Requires-Dist: lung-nodule-mlx==0.2.2; extra == 'all'
Requires-Dist: medsam2-mlx==0.2.2; extra == 'all'
Requires-Dist: mlx-generate==0.4.1; extra == 'all'
Requires-Dist: mlx-reason-ct==0.3.3; extra == 'all'
Requires-Dist: mlx-segment-ct==0.3.0; extra == 'all'
Requires-Dist: mlxradiomics[io]==0.1.0.dev4; extra == 'all'
Requires-Dist: nibabel<6,>=5.4.2; extra == 'all'
Requires-Dist: nnunet-mlx==0.5.2; extra == 'all'
Requires-Dist: radimagenet-mlx==0.2.2; extra == 'all'
Requires-Dist: sam3-mlx[video]==0.1.5; extra == 'all'
Requires-Dist: segresnet-mlx==0.2.2; extra == 'all'
Requires-Dist: swin-unetr-mlx==0.2.2; extra == 'all'
Requires-Dist: synthseg-mlx==0.2.2; extra == 'all'
Requires-Dist: totalsegmentator-mlx==0.1.2.post1; extra == 'all'
Requires-Dist: unest-mlx==0.2.3; extra == 'all'
Provides-Extra: generate
Requires-Dist: fdg-pet-ct-mlx==0.2.2; extra == 'generate'
Requires-Dist: lesiondiffusion-mlx==0.2.2; extra == 'generate'
Requires-Dist: mlx-generate==0.4.1; extra == 'generate'
Requires-Dist: mlx-reason-ct==0.3.3; extra == 'generate'
Requires-Dist: nibabel<6,>=5.4.2; extra == 'generate'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.2; extra == 'mcp'
Provides-Extra: segment
Requires-Dist: biomedparse-mlx==0.1.2; extra == 'segment'
Requires-Dist: flexible-unet-mlx==0.2.2; extra == 'segment'
Requires-Dist: flexray-mlx==0.2.2; extra == 'segment'
Requires-Dist: medsam2-mlx==0.2.2; extra == 'segment'
Requires-Dist: mlx-segment-ct==0.3.0; extra == 'segment'
Requires-Dist: nnunet-mlx==0.5.2; extra == 'segment'
Requires-Dist: sam3-mlx[video]==0.1.5; extra == 'segment'
Requires-Dist: segresnet-mlx==0.2.2; extra == 'segment'
Requires-Dist: swin-unetr-mlx==0.2.2; extra == 'segment'
Requires-Dist: synthseg-mlx==0.2.2; extra == 'segment'
Requires-Dist: totalsegmentator-mlx==0.1.2.post1; extra == 'segment'
Requires-Dist: unest-mlx==0.2.3; extra == 'segment'
Provides-Extra: setup
Requires-Dist: huggingface-hub<2,>=0.34; extra == 'setup'
Requires-Dist: uv<1,>=0.8; extra == 'setup'
Provides-Extra: vision
Requires-Dist: lung-nodule-mlx==0.2.2; extra == 'vision'
Requires-Dist: mlxradiomics[io]==0.1.0.dev4; extra == 'vision'
Requires-Dist: radimagenet-mlx==0.2.2; extra == 'vision'
Description-Content-Type: text/markdown

# MedMLX

## Model setup for applications

Install the `setup` extra to use `medmlx setup MODEL --progress`. It reuses
explicitly supplied model directories, the MedMLX asset cache, or the Hub cache,
then downloads missing native files and retains publisher notices. It returns
the runner arguments for the application to remember. Downloads can be resumed
by running setup again; `--plan` only describes the operation.

`medmlx.list_setup_plans()`, `setup_plan(model_id)`, and
`setup_model(model_id, existing_paths=..., progress=...)` expose the same actions
to Python clients. The default asset cache search is `~/.cache/medmlx` (override
with `MEDMLX_ASSET_CACHE`); downloads use the normal Hugging Face cache. Setup
supports published VISTA3D CT, Reason-CT, FleXray flagship, and named BraTS bundles,
plus the radiomics runtime. Other checkpoints require their provider's setup.
Runtime installation uses this release's family pins. Frozen applications must
already bundle the runtime; setup can still download their model files. An
already installed runtime is detected by package metadata and is not checked
against the family pin or imported by that check.
Setup checks required files and available provider admission contracts. Model
execution retains responsibility for tensor compatibility and input validation.

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.

[Models](https://github.com/MedMLX) · [Docs](https://github.com/MedMLX/medmlx/blob/main/docs/declaring-models.md) · [Website](https://medmlx.org)

![Outputs across CT, PET/CT, radiographs, endoscopy and MRI](https://raw.githubusercontent.com/MedMLX/medmlx/main/docs/gallery.jpg)

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

## Install

Install all model families with MCP and model setup support:

```sh
uv venv --python 3.13
source .venv/bin/activate
uv pip install "medmlx[all,mcp,setup]"
medmlx models
```

Choose `segment`, `generate` or `vision` instead of `all` for a smaller install.
The segment extra includes SAM3 image/video support; generate includes NV-Reason-CT
and the weight-free FDG PET adapter. Model weights have their own download and access
requirements. Provisional `medgemma` and `lingshu` adapters use an explicitly selected
separate MedVLM environment; real-checkpoint inference through these bridges is
unqualified. The MedVLM runtime is not bundled because its MLX and Transformers
requirements conflict with the unified environment. See the
[bridge setup and limits](https://github.com/MedMLX/medmlx/blob/main/docs/medvlm-bridge.md) and
[dependency compatibility notes](https://github.com/MedMLX/medmlx/blob/main/docs/release-notes.md).

## Run a model

```sh
medmlx describe totalsegmentator
medmlx readiness totalsegmentator --arguments arguments.json --root /path/to/work
medmlx checkpoints --model-id nnunet
medmlx run totalsegmentator --arguments arguments.json --root /path/to/work
```

`describe` includes the provider's full instructions and argument descriptions,
including documented units and ranges. Descriptions reproduce provider documentation;
they do not establish validated constraints or numerical qualification. Relative
paths resolve against `--root`.
Readiness preserves `ready` as a boolean for imports/provider checks and Metal;
`runtime_ready` makes that same limited meaning explicit. Neither validates run
inputs or weights. The separate `run_ready` is `false` for a known blocker and
`null` while input/checkpoint contents remain unverified; this check never returns
`run_ready=true`. Passing arguments checks names, required arguments and local
input/weight path existence, without running inference or creating outputs.

`checkpoints` lists five source references, including catalog-only liver and AutoPET
entries for the general nnU-Net provider. It neither stages assets nor qualifies a
checkpoint. The same action is available as `list_checkpoints` in Python and MCP.

```python
import json
from pathlib import Path
import medmlx

arguments = json.loads(Path("arguments.json").read_text())
result = medmlx.run("totalsegmentator", arguments=arguments, root="/path/to/work")
```

For an MCP client, use `medmlx serve --root /path/to/work` as its stdio command.
Jobs belong to that server session; disconnecting cancels workers and their child
processes. Client registration and persistent filesystem access are configured by
that client, not changed by this package. Some providers fetch default assets when
paths are omitted; supply explicit local checkpoints for offline execution.
See the [MCP guide](https://github.com/MedMLX/medmlx/blob/main/docs/mcp.md) for client setup, tools, and a complete job workflow.
For checkpoint conversion and development, see [conversion](https://github.com/MedMLX/medmlx/blob/main/conversion/README.md) and [core](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.

For research and education. Outputs require human review.
