Metadata-Version: 2.4
Name: mlx-reason-ct
Version: 0.3.2
Summary: Native MLX port of NVIDIA NV-Reason-CT for 3D CT reasoning on Apple Silicon
Project-URL: Homepage, https://github.com/MedMLX/MLX-Reason-CT
Project-URL: Repository, https://github.com/MedMLX/MLX-Reason-CT
Project-URL: Documentation, https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/technical.md
Project-URL: Issues, https://github.com/MedMLX/MLX-Reason-CT/issues
Project-URL: Weights, https://huggingface.co/josand/MLX-Reason-CT
Author: Joseph Sandoval
License-Expression: Apache-2.0 AND MIT AND BSD-3-Clause AND LicenseRef-OpenMDW-1.1
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Keywords: apple-silicon,ct,medical-imaging,mlx,nv-reason-ct
Classifier: Operating System :: MacOS :: MacOS X
Requires-Python: <3.15,>=3.13
Requires-Dist: huggingface-hub==1.23.0
Requires-Dist: jinja2==3.1.6
Requires-Dist: medmlx-core==0.2.3
Requires-Dist: mlx==0.32.4; sys_platform == 'darwin' and platform_machine == 'arm64'
Requires-Dist: nibabel==5.4.2
Requires-Dist: numpy==2.3.5
Requires-Dist: safetensors==0.8.0
Requires-Dist: scipy==1.18.1
Requires-Dist: tokenizers==0.22.2
Description-Content-Type: text/markdown

# MLX-Reason-CT

Native MLX port of [NVIDIA NV-Reason-CT](https://huggingface.co/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](https://github.com/MedMLX/MLX-Reason-CT/releases) ·
[Weights](https://huggingface.co/josand/MLX-Reason-CT) ·
[Usage](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/usage.md) ·
[Paper](https://arxiv.org/abs/2609.27511) ·
[HF collection](https://huggingface.co/collections/josand/medmlx-mlx-reason-ct-6ac85b2663d2ca5df1887db2)

Part of [MedMLX](https://github.com/MedMLX).
[Technical notes](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/technical.md)

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

## Requirements

Supported platform: macOS arm64 on an Apple Silicon Mac with Metal GPU access,
Python 3.13 or 3.14 and [uv](https://docs.astral.sh/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

```bash
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:

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

For abdomen CT:

```bash
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](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/usage.md).

For source development, clone
[this repository](https://github.com/MedMLX/MLX-Reason-CT) 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](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/synthetic-walkthrough.md). It covers installation,
bundle verification, input generation and completion checks.

### Python

```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](https://github.com/MedMLX/medmlx) as `mlx-reason-ct`. Full runner
contract in [docs/usage.md](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/usage.md#medmlx-runner).

## 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](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/technical.md) and [usage guide](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/usage.md).
Seeded test references are recorded on darwin-arm64; [verification scope](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/verification.md) 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](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/docs/verification.md#source-bf16-optimization-measurement-2026-10-09).

## Intended use

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

## License

Original port contributions: [Apache-2.0](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/LICENSE), Joseph Sandoval.
NVIDIA model architecture, processor policy and weights retain
[OpenMDW-1.1](https://huggingface.co/nvidia/NV-Reason-CT/blob/386b93e034983f6c1fc841a43833a1b6a0cd9c13/LICENSE), NVIDIA CORPORATION & AFFILIATES.
Bundled Apple and PyTorch-derived portions retain MIT and BSD-3-Clause terms.
[Third-party notices](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.3.2/THIRD_PARTY_NOTICES.md).
