Clean model card and use MLX-Reason-CT naming

README.md

@@ -1,116 +1,156 @@
 ---
 license: openmdw-1.1
+language:
+- en
 library_name: mlx
+base_model: nvidia/NV-Reason-CT
+pipeline_tag: image-text-to-text
+inference: false
 tags:
-- medical-imaging
+- mlx
+- native-mlx
 - apple-silicon
-- research
-language:
-- en
+- fp32
+- ct
+- medical-imaging
+- nv-reason-ct
+- 3d-vlm
+- vision-language
+- radiology
+- report-generation
 ---
-# NV-Reason-CT 386b93e0, FP32, chest structured report, greedy, max_new_tokens 512, thinking off
 
-Native MLX package: [MLX-Reason-CT](https://github.com/MedMLX/MLX-Reason-CT.git).
-Evaluated revision: `eb2c10baf688b32eee082dbb8973e88b4555db7a`.
+# 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**.
+[GitHub releases](https://github.com/MedMLX/MLX-Reason-CT/releases) ·
+[Usage](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.2.4/docs/usage.md) ·
+[Paper](https://arxiv.org/abs/2609.27511) ·
+[Public reference card](https://huggingface.co/josand/MLX-Reason-CT)
 
-This card describes the one configuration evaluated in the MedMLX paper. It is research software; the single-case comparison does not estimate clinical accuracy.
+**Requires the companion `mlx-reason-ct` runtime.** Follow the quick start below.
+Hugging Face's generated "Use this model" snippet uses `mlx-vlm`, which does not
+support this 3D CT architecture; generic `mlx-lm` loaders are also incompatible.
 
-## Source and checkpoint
+## Requirements
 
-Original publisher: NVIDIA.
-Original implementation: [https://huggingface.co/nvidia/NV-Reason-CT](https://huggingface.co/nvidia/NV-Reason-CT).
-Source revision or version: `386b93e034983f6c1fc841a43833a1b6a0cd9c13`.
-Original checkpoint: https://huggingface.co/nvidia/NV-Reason-CT/resolve/386b93e034983f6c1fc841a43833a1b6a0cd9c13/model.safetensors
+Supported platform: macOS arm64 on an Apple Silicon Mac with Metal GPU access,
+Python 3.12 and [uv](https://docs.astral.sh/uv/). Inference fails explicitly when
+Metal is unavailable.
 
-Conversion: mlx-reason-ct convert --source-dir <pinned snapshot> --output-dir work/runs/weights/nv-reason-ct (lossless BF16->FP32); the pre-existing radnn conversion was rejected by the package (engine radnn.nv_reason_ct_mlx.v1 differs from the pinned nv_reason_ct_mlx.fp32.v1).
-Conversion changes tensor layout or storage as specified by the native package; it does not retrain the model.
+`v0.2.4` uses the public Apache-2.0 `medmlx-core==0.1.2` runtime from PyPI.
 
-## Recorded example
+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.
 
-LUNA16 subset0 / 1.3.6.1.4.1.14519.5.2.1.6279.6001.105756658031515062000744821260
+## Quick start
 
-```python
-from mlx_reason_ct.medmlx import run
+```bash
+uv tool install --python 3.12 \
+  https://github.com/MedMLX/MLX-Reason-CT/releases/download/v0.2.4/mlx_reason_ct-0.2.4-py3-none-any.whl
 
-# Replace file and directory names with your locally obtained inputs and weights.
-kwargs = {
-    "image_path": "luna-case.nii.gz",
-    "weights_path": "nv-reason-ct",
-    "output_dir": "out",
-    "anatomy_region": "chest",
-    "overwrite": True
-}
-result = run(**kwargs)
-print(result["outputs"])
+uvx --from huggingface_hub hf download MedMLX/MLX-Reason-CT --local-dir models
 ```
 
-Native result: **success**. Original-code comparison: **pass**, `token_identical` = `True`.
-
-The recorded CPU FP32 profile reproduces greedy output tokens. Do not generalize this comparison to the original CUDA BF16 profile or diagnostic accuracy.
-
-The complete [native run](native-run.json) and [original-code comparison](reference-comparison.json) retain commands, geometry, precision, and output-specific checks. Use the [replay harness](https://github.com/MedMLX/Med-MLX/blob/main/benchmarks/README.md) to substitute local paths. The package README documents installation and conversion.
-
-## Distribution terms
-
-Upstream code: **OpenMDW-1.1**. Weights: **OpenMDW-1.1**.
-Converted weights are hosted in this repository.
-
-The recorded CPU FP32 profile reproduces greedy output tokens. Do not generalize this comparison to the original CUDA BF16 profile or diagnostic accuracy. Converted weights may retain the identified upstream license and required notices; the accompanying notices describe the redistribution terms.
-
-Full [upstream license](LICENSE) accompanies any weight distribution. The [retained component notices](THIRD_PARTY_NOTICES.md) accompany the prepared bundle.
-
-Required notices:
-
-- Retain the applicable license, copyright and attribution notices; identify the upstream checkpoint, authors, and MLX conversion changes.
-- Include OpenMDW-1.1 and retain all applicable copyright and origin notices, including component notices.
-- Retain component notices identified by radnn@cbaa1ac:THIRD_PARTY_NOTICES.md: NVIDIA 2026; Qwen/HuggingFace 2025; MLX/MLX-LM Apple MIT; MONAI, dynamic-network-architectures, timm and Transformers Apache-2.0; PyTorch/Caffe2 BSD; FlashAttention BSD-3-Clause.
-
-Review sources:
-
-- https://huggingface.co/nvidia/NV-Reason-CT
-- https://huggingface.co/nvidia/NV-Reason-CT/resolve/386b93e034983f6c1fc841a43833a1b6a0cd9c13/model.safetensors
-- https://huggingface.co/nvidia/NV-Reason-CT/blob/386b93e034983f6c1fc841a43833a1b6a0cd9c13/LICENSE
-
-## Packaged files
-
-- `chat_template.jinja`
-- `config.json`
-- `generation_config.json`
-- `image_processor_3d/preprocessor_config.json`
-- `mlx/embedding.safetensors`
-- `mlx/layer_00.safetensors`
-- `mlx/layer_01.safetensors`
-- `mlx/layer_02.safetensors`
-- `mlx/layer_03.safetensors`
-- `mlx/layer_04.safetensors`
-- `mlx/layer_05.safetensors`
-- `mlx/layer_06.safetensors`
-- `mlx/layer_07.safetensors`
-- `mlx/layer_08.safetensors`
-- `mlx/layer_09.safetensors`
-- `mlx/layer_10.safetensors`
-- `mlx/layer_11.safetensors`
-- `mlx/layer_12.safetensors`
-- `mlx/layer_13.safetensors`
-- `mlx/layer_14.safetensors`
-- `mlx/layer_15.safetensors`
-- `mlx/layer_16.safetensors`
-- `mlx/layer_17.safetensors`
-- `mlx/layer_18.safetensors`
-- `mlx/layer_19.safetensors`
-- `mlx/layer_20.safetensors`
-- `mlx/layer_21.safetensors`
-- `mlx/layer_22.safetensors`
-- `mlx/layer_23.safetensors`
-- `mlx/layer_24.safetensors`
-- `mlx/layer_25.safetensors`
-- `mlx/layer_26.safetensors`
-- `mlx/layer_27.safetensors`
-- `mlx/layer_28.safetensors`
-- `mlx/layer_29.safetensors`
-- `mlx/layer_30.safetensors`
-- `mlx/layer_31.safetensors`
-- `mlx/manifest.json`
-- `mlx/norm.safetensors`
-- `mlx/vision.safetensors`
-- `tokenizer.json`
+Authenticate with `hf auth login` if repository access is required.
+
+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.
+
+For an existing Python 3.12 environment, use `pip install` with the same release-wheel URL.
+Wheel and source archives are also available in the
+[GitHub release](https://github.com/MedMLX/MLX-Reason-CT/releases/tag/v0.2.4).
+For source development, clone [the repository](https://github.com/MedMLX/MLX-Reason-CT)
+and run `make env`; use `uv run mlx-reason-ct` for the commands above.
+The source checkout additionally supports plain centered cropping and follow-up
+history, which are not in 0.2.4; see the
+[source usage guide](https://github.com/MedMLX/MLX-Reason-CT/blob/main/docs/usage.md).
+
+For a generated input with no patient data, follow the
+[synthetic CT walkthrough](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.2.4/docs/synthetic-walkthrough.md).
+It covers installation, bundle verification, input generation and completion checks.
+
+## 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
+
+This repository contains the converted organization bundle sourced from NVIDIA
+revision `386b93e034983f6c1fc841a43833a1b6a0cd9c13`, using lossless BF16-to-FP32
+expansion and the `nv_reason_ct_mlx.fp32.v1` format. No retraining was performed.
+
+The retained LUNA16 chest comparison used greedy generation, 512 maximum new
+tokens and thinking disabled. It completed successfully and reproduced the
+reference CPU FP32 output tokens. This does not establish equivalence to the
+original CUDA BF16 profile or estimate diagnostic accuracy.
+
+[Native run](https://huggingface.co/MedMLX/MLX-Reason-CT/blob/main/native-run.json) ·
+[Original-code comparison](https://huggingface.co/MedMLX/MLX-Reason-CT/blob/main/reference-comparison.json).
+Evaluated package revision: `eb2c10baf688b32eee082dbb8973e88b4555db7a`.
+
+Inference defaults to FP32 with weights converted directly from the
+original BF16 checkpoint, without retraining.
+[Implementation and verification details](https://github.com/MedMLX/MLX-Reason-CT/blob/v0.2.4/docs/usage.md),
+and the limits of its darwin-arm64 component references are in the companion repository.
+[Upstream model card and limitations](https://huggingface.co/nvidia/NV-Reason-CT).
+
+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.2.3/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
+
+Weights: [OpenMDW-1.1](https://huggingface.co/MedMLX/MLX-Reason-CT/blob/main/LICENSE),
+Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES.
+Underlying Qwen3.5 terms: [Apache-2.0](https://huggingface.co/josand/MLX-Reason-CT/blob/main/APACHE-2.0.txt).
+
+Port code: [Apache-2.0](https://github.com/MedMLX/MLX-Reason-CT/blob/main/LICENSE),
+Copyright (c) 2026 Joseph Sandoval.
+[Third-party notices](https://github.com/MedMLX/MLX-Reason-CT/blob/main/THIRD_PARTY_NOTICES.md).
+
+The hosted bundle retains [attribution](https://huggingface.co/MedMLX/MLX-Reason-CT/blob/main/NOTICE)
+and [component notices](https://huggingface.co/MedMLX/MLX-Reason-CT/blob/main/THIRD_PARTY_NOTICES.md).