Metadata-Version: 2.5
Name: biomedparse-mlx
Version: 0.1.1
Summary: Native MLX inference for BioMedParse v2 on Apple Silicon
Author: Joseph Sandoval, Alfredo Sandoval Jr.
License-Expression: Apache-2.0 AND MIT AND BSD-3-Clause
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Classifier: Operating System :: MacOS :: MacOS X
Requires-Python: <3.15,>=3.13
Requires-Dist: medmlx-core==0.2.3
Requires-Dist: nibabel<6,>=5.3
Requires-Dist: numpy<3,>=2
Requires-Dist: pillow<14,>=13
Requires-Dist: pydicom<4,>=3
Requires-Dist: scikit-image<1,>=0.25
Requires-Dist: tokenizers<0.23,>=0.22
Provides-Extra: assets
Requires-Dist: huggingface-hub<2,>=1; extra == 'assets'
Provides-Extra: conversion
Requires-Dist: safetensors<1,>=0.6; extra == 'conversion'
Requires-Dist: torch<3,>=2.6; extra == 'conversion'
Provides-Extra: dev
Requires-Dist: hypothesis<7,>=6.140; extra == 'dev'
Requires-Dist: pyright==1.1.414; extra == 'dev'
Requires-Dist: pytest<10,>=8.4; extra == 'dev'
Requires-Dist: ruff<1,>=0.13; extra == 'dev'
Provides-Extra: oracle
Requires-Dist: fvcore>=0.1.5; extra == 'oracle'
Requires-Dist: hydra-core<2,>=1.3; extra == 'oracle'
Requires-Dist: safetensors<1,>=0.6; extra == 'oracle'
Requires-Dist: simpleitk<3,>=2.4; extra == 'oracle'
Requires-Dist: timm<2,>=1; extra == 'oracle'
Requires-Dist: torch<3,>=2.6; extra == 'oracle'
Requires-Dist: transformers<6,>=5; extra == 'oracle'
Description-Content-Type: text/markdown

# biomedparse-mlx

Native MLX port of [Microsoft BioMedParse v2](https://github.com/microsoft/BiomedParse/tree/v2)
for Apple Silicon. Segment medical images from text prompts, locally on Mac.

- Text-guided 3D segmentation with multiple prompts and labels
- Raw NIfTI and DICOM windowing, with geometry-preserving NIfTI mask output
- Float32 model execution on Metal; PyTorch is used for conversion and oracle tests
- A 2D image path with overlapping prompt masks; dedicated 2D weights remain unqualified

Part of [MedMLX](https://github.com/MedMLX).
[Technical notes](https://github.com/MedMLX/biomedparse-mlx/blob/main/docs/technical.md) · [Usage](https://github.com/MedMLX/biomedparse-mlx/blob/main/docs/usage.md)

[Quick start](#quick-start) · [Input and output](#input-and-output) · [Technical details](#technical-details) · [License](#license)

## Requirements

Apple Silicon Mac with Metal, Python 3.13 or 3.14 and [uv](https://docs.astral.sh/uv/).
The released checkpoint requires access to the gated Microsoft model on Hugging Face.

## Quick start

Prepare the locked checkout and local checkpoint assets:

```bash
gh repo clone MedMLX/biomedparse-mlx
cd biomedparse-mlx
make env
MACOSX_DEPLOYMENT_TARGET=27.0 uv sync --locked --extra dev --extra oracle --extra conversion --extra assets

uv run --locked --no-sync hf download microsoft/BiomedParse biomedparse_v2.ckpt \
  --revision e473e5b2b1a3f44649734afd3dc7cf1770aaa9e2 --local-dir weights/source
uv run --locked --no-sync hf download openai/clip-vit-base-patch32 tokenizer.json \
  --revision 3d74acf9a28c67741b2f4f2ea7635f0aaf6f0268 --local-dir weights

uv run --locked --no-sync biomedparse-mlx convert \
  --source weights/source/biomedparse_v2.ckpt --output weights/biomedparse-v2.npz
```

The source checkpoint is about 4.46 GB. Conversion writes a float32 tensor bundle
and a versioned receipt. Inference uses local assets without implicit downloads.

Segment a preprocessed volume:

```bash
uv run --locked --no-sync biomedparse-mlx segment \
  --image scan.npy --weights weights/biomedparse-v2.npz --tokenizer weights/tokenizer.json \
  --prompt 'Visualization of the liver in abdominal CT imaging' --label 6 \
  --output-dir outputs/liver --slice-batch-size 2 --seed 7
```

Repeat `--prompt` and `--label` for multiple structures. Existing outputs require
`--overwrite`. Python usage, raw-image windowing, instance segmentation and the
`segment-2d` command are described in [docs/usage.md](https://github.com/MedMLX/biomedparse-mlx/blob/main/docs/usage.md).
The model is discoverable by [medmlx](https://github.com/MedMLX/medmlx) as `biomedparse-v2`.

## Input and output

Volumes are preprocessed numeric `.npy` arrays or `.npz` files containing `imgs`
in the upstream 0..255 intensity range. Raw NIfTI volumes and DICOM slices require
explicit `--modality` and, for CT, `--ct-site` windowing options. Volume slicing
follows upstream's fixed shape heuristic.

The volume path writes `segmentation.npz` with uint16 labels on the original array
grid, prompt-by-slice existence probabilities, and `run.json`. NIfTI inputs also
produce `segmentation.nii.gz` on the source affine. The 2D path returns separate,
potentially overlapping masks and probabilities per prompt.

## Technical details

The native graph follows the pinned BioMedParse v2 architecture and checkpoint
contract. Controlled oracle comparisons replay upstream attention masks; matching
integer seeds alone does not align Torch and MLX sampling. Recorded qualification
covers bounded synthetic and AMOS cases. Dedicated 2D weights, broader task
accuracy and clinical performance remain unqualified.

Architecture, numerical tolerances, development checks and recorded measurements
are in [docs/technical.md](https://github.com/MedMLX/biomedparse-mlx/blob/main/docs/technical.md).

## Intended use

Intended for research and education, not clinical diagnosis or treatment decisions.
Outputs require human review.

## License

Original contributions: Apache-2.0; see [LICENSE](https://github.com/MedMLX/biomedparse-mlx/blob/main/LICENSE). Upstream MIT/BSD notices and full
license texts are retained in [THIRD_PARTY_NOTICES.md](https://github.com/MedMLX/biomedparse-mlx/blob/main/THIRD_PARTY_NOTICES.md).
Model weights have separate publisher terms: Microsoft's model card declares
CC-BY-NC-SA-4.0. Weights, tokenizers, datasets and masks are excluded from Git.

## Implementation mapping

[Central implementation map](https://github.com/MedMLX/Med-MLX/blob/main/implementation-maps/biomedparse-mlx.json) records upstream-to-native changes, source references and qualification scope.
