MLX-Reason-CT

Native MLX port of NVIDIA NV-Reason-CT for Apple Silicon. Run 3D CT reasoning and report generation locally on Mac.

• Chest and abdomen CT
• Structured reports and CT question answering
• Local NIfTI input with Apple Silicon GPU acceleration
• FP32 by default, with explicit BF16 arithmetic profiles on Metal

MLX port by Joseph Sandoval. Releases · Weights · Usage · Paper · HF collection

Part of MedMLX. Technical notes

Quick start · Input and output · Technical details · License

Requirements

Supported platform: macOS arm64 on an Apple Silicon Mac with Metal GPU access, Python 3.13 or 3.14 and uv. Inference fails explicitly when Metal is unavailable.

Weights occupy 17.4 GB. Measured peak MLX memory use is about 22.7 GB; allow additional unified memory for preprocessing, macOS and other apps.

Quick start

uv tool install --python 3.13 \
  https://github.com/MedMLX/MLX-Reason-CT/releases/download/v0.3.2/mlx_reason_ct-0.3.2-py3-none-any.whl

mlx-reason-ct download \
  --revision c690a63888b9c6c9bd006687335fbd650eb60275 \
  --model-dir models

Generate a chest CT report:

mlx-reason-ct report \
  --input ct.nii.gz --model-dir models --output-dir outputs

For abdomen CT:

mlx-reason-ct report \
  --input ct.nii.gz --model-dir models --output-dir outputs \
  --anatomy-region abdomen

To ask a question about the CT, set --prompt to your question. Use --anatomy-region none for the processor's plain centered crop and --history for follow-up questions about the same CT; see usage.

For source development, clone this repository and run make env; use uv run mlx-reason-ct for the commands above.

For a generated input with no patient data, follow the synthetic CT walkthrough. It covers installation, bundle verification, input generation and completion checks.

Python

from mlx_reason_ct.medmlx import run

result = run(image_path="ct.nii.gz", weights_path="models", output_dir="outputs")
print(result["outputs"]["report"])

Takes the same options as the CLI (prompt, anatomy_region, enable_thinking, precision, overwrite, history; anatomy_region=None for the centered crop). The model is also discoverable by medmlx as mlx-reason-ct. Full runner contract in docs/usage.md.

Input and output

Input is one 3D CT volume in NIfTI format (.nii or .nii.gz) with Hounsfield Unit values and valid spatial geometry. DICOM and 2D images are unsupported.

The upstream crop locates the chest from enclosed air. On whole-body scans, especially with arms raised, it can select the head and neck instead; crop such volumes to the chest or abdomen before running.

Each run writes:

• report.txt — generated response
• model_response.json — response, reasoning (with --enable-thinking) and generation metadata
• run.json — execution metadata

Version 0.2.4 removes a trailing empty <answer></answer> element from the saved report in both text and JSON, while preserving reasoning and nonempty answer elements.

Technical details

Inference defaults to FP32 with weights converted directly from the original BF16 checkpoint, without retraining. See the source and arithmetic contracts and usage guide. Seeded test references are recorded on darwin-arm64; verification scope explains their bounds and what they do not establish.

Version 0.2.3 includes faster source-BF16 projection and attention kernels. On one M1 Max synthetic case, cached full-model time fell from 17:54 in the preceding source build to 14:49, with bitwise-unchanged recorded outputs. Full BF16 qualification remains incomplete; see the benchmark and limits.

Intended use

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

License

Original port contributions: Apache-2.0, Joseph Sandoval. NVIDIA model architecture, processor policy and weights retain OpenMDW-1.1, NVIDIA CORPORATION & AFFILIATES. Bundled Apple and PyTorch-derived portions retain MIT and BSD-3-Clause terms. Third-party notices.