Add native MLX model card and conversion guide

README.md

@@ -0,0 +1,119 @@
+---
+library_name: mlx
+license: other
+tags:
+- medical-imaging
+- apple-silicon
+- research
+- inference
+- conversion
+- model-card-only
+language:
+- en
+license_name: upstream-component-terms
+license_link: https://github.com/HengruiTianSJTU/LesionDiffusion
+pipeline_tag: image-to-image
+---
+
+# LesionDiffusion for MLX
+
+Native MLX LesionDiffusion synthesis on Apple Silicon using LMNet, LINet, and VQ components. The recorded paper configuration inserts a liver tumor into a prepared CT crop; current conditioned inference is documented separately below.
+
+**Repository contents:** model card and local conversion instructions. No checkpoint, tokenizer, medical image, or output data is included. Obtain original assets directly from their publishers under the applicable terms.
+
+Requires an Apple Silicon Mac with Metal and Python 3.12/3.13. Model inference uses MLX; PyTorch is used for one-time checkpoint conversion and optional upstream comparisons. Intended for research and education; clinical diagnostic performance has not been established.
+
+Native MLX package: [lesiondiffusion-mlx](https://github.com/MedMLX/lesiondiffusion-mlx).
+Evaluated revision: `9b7a15eef808a38ab56e82325c22f209f69b9b78`.
+
+This card describes the one configuration evaluated in the MedMLX paper. It is research software; the single-case comparison does not estimate clinical accuracy.
+
+## Source and checkpoint
+
+Original publisher: HengruiTianSJTU.
+Original implementation: [https://github.com/HengruiTianSJTU/LesionDiffusion](https://github.com/HengruiTianSJTU/LesionDiffusion).
+Source revision or version: `880736e2b8a4d9becdb6594da7f8af6db19d04d1`.
+Original checkpoint: Component locations are in the native run record and the upstream package documentation.
+
+Conversion: lesiondiffusion_mlx.write_conversion (README recipe), using the upstream component checkpoints and an explicitly supplied BiomedCLIP tokenizer.
+Conversion changes tensor layout or storage as specified by the native package; it does not retrain the model.
+
+## Install and convert
+
+Install the native package with conversion support:
+
+```bash
+uv pip install "lesiondiffusion-mlx[conversion] @ git+https://github.com/MedMLX/lesiondiffusion-mlx.git"
+```
+
+Obtain the LMNet, LINet, and VQ checkpoints through the [official upstream project](https://github.com/HengruiTianSJTU/LesionDiffusion), together with its BiomedCLIP `tokenizer.json`. Component terms remain separate. Convert the explicitly selected local assets:
+
+```python
+from pathlib import Path
+from lesiondiffusion_mlx import write_conversion
+
+write_conversion(
+    checkpoints={
+        "lmnet": Path("LMNet.ckpt"),
+        "linet": Path("LINet.ckpt"),
+        "vq": Path("VQ.ckpt"),
+    },
+    tokenizer_path=Path("tokenizer.json"),
+    output_dir=Path("lesiondiffusion"),
+)
+```
+
+The [package README](https://github.com/MedMLX/lesiondiffusion-mlx#input-and-output) defines the CT and organ-mask preparation contract. The example below explicitly selects the paper's `source` inference mode. The package currently defaults to `conditioned`; its source-parity result must not be applied to that mode.
+
+## Recorded example
+
+AMOS22 (validation) / amos_0008; AMOS22 (validation) / amos_0008 label 6 (liver)
+
+```python
+from lesiondiffusion_mlx.medmlx import run
+
+# Replace file and directory names with your locally obtained inputs and weights.
+kwargs = {
+    "image_path": "amos_0008_ct_1mm_ras_160x160x128.nii.gz",
+    "organ_mask_path": "amos_0008_liver_1mm_ras_160x160x128.nii.gz",
+    "output_dir": "out",
+    "weights_path": "lesiondiffusion",
+    "organ": "liver",
+    "lesion_type": "tumor",
+    "bbox_size_mm": [
+        30,
+        30,
+        20
+    ],
+    "placement": "inside_parenchyma",
+    "inference_mode": "source",
+    "diffusion_steps": 200,
+    "overwrite": False,
+    "seed": 23
+}
+result = run(**kwargs)
+print(result["outputs"])
+```
+
+Native result: **success**. Original-code comparison: **pass**, `cosine_similarity` = `0.9999697715207947`.
+
+Full controlled 200-step paired reference completed October 12; image cosine 0.99996977 and lesion Dice 1.0. Density and outside-lesion reconstruction limitations remain.
+
+The complete [native run](https://github.com/MedMLX/Med-MLX/blob/main/results/runs/lesiondiffusion.json) and [original-code comparison](https://github.com/MedMLX/Med-MLX/blob/main/results/reference/lesiondiffusion.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.
+
+The current package defaults to `inference_mode="conditioned"`, which enables LINet text context and native FP16 convolution. The example above explicitly selects `source` to retain the paper's evaluated mode. The [October 12 follow-up](https://github.com/MedMLX/Med-MLX/blob/main/results/lesiondiffusion-conditioned-20261012.json) records a 452.6 s 200-step run with −20.6 HU lesion-minus-nearby-liver contrast and a 128.4 s 50-step draw with −19.0 HU contrast on the same case. This additional visibility check does not extend the paper's source-parity result to conditioned mode or establish clinical validity.
+
+## Distribution terms
+
+Upstream code: **MIT**. Weights: **Unresolved; retrieve directly from the original publisher**.
+Eligible route: **converter**. Prepared locally; no converted weights uploaded.
+
+Full controlled 200-step paired reference completed October 12; image cosine 0.99996977 and lesion Dice 1.0. Density and outside-lesion reconstruction limitations remain. No unambiguous complete-component redistribution grant verified; distribute conversion code and refer users to the original weights.
+
+Required notices:
+
+- Retain the applicable license, copyright and attribution notices; identify the upstream checkpoint, authors, and MLX conversion changes.
+
+Review sources:
+
+- https://github.com/HengruiTianSJTU/LesionDiffusion