Instructions to use josand/MLX-Reason-CT with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use josand/MLX-Reason-CT with MLX:

# Make sure mlx-vlm is installed
# pip install --upgrade mlx-vlm

from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template
from mlx_vlm.utils import load_config

# Load the model
model, processor = load("josand/MLX-Reason-CT")
config = load_config("josand/MLX-Reason-CT")

# Prepare input
image = ["http://images.cocodataset.org/val2017/000000039769.jpg"]
prompt = "Describe this image."

# Apply chat template
formatted_prompt = apply_chat_template(
    processor, config, prompt, num_images=1
)

# Generate output
output = generate(model, processor, formatted_prompt, image)
print(output)

Notebooks
Google Colab
Kaggle
Local Apps Settings
LM Studio

How to use josand/MLX-Reason-CT with Pi:

Start the MLX server

# Install MLX LM:
uv tool install mlx-lm
# Start a local OpenAI-compatible server:
mlx_lm.server --model "josand/MLX-Reason-CT"

Configure the model in Pi

# Install Pi:
npm install -g @earendil-works/pi-coding-agent
# Add to ~/.pi/agent/models.json:
{
  "providers": {
    "mlx-lm": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "josand/MLX-Reason-CT"
        }
      ]
    }
  }
}

Run Pi

# Start Pi in your project directory:
pi

Hermes Agent

How to use josand/MLX-Reason-CT with Hermes Agent:

Start the MLX server

# Install MLX LM:
uv tool install mlx-lm
# Start a local OpenAI-compatible server:
mlx_lm.server --model "josand/MLX-Reason-CT"

Configure Hermes

# Install Hermes:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
# Point Hermes at the local server:
hermes config set model.provider custom
hermes config set model.base_url http://127.0.0.1:8080/v1
hermes config set model.default josand/MLX-Reason-CT

Run Hermes

hermes

Atomic Chat

OpenClaw

How to use josand/MLX-Reason-CT with OpenClaw:

Start the MLX server

# Install MLX LM:
uv tool install mlx-lm
# Start a local OpenAI-compatible server:
mlx_lm.server --model "josand/MLX-Reason-CT"

Configure OpenClaw

# Install OpenClaw:
npm install -g openclaw@latest
# Register the local server and set it as the default model:
openclaw onboard --non-interactive --mode local \
  --auth-choice custom-api-key \
  --custom-base-url http://127.0.0.1:8080/v1 \
  --custom-model-id "josand/MLX-Reason-CT" \
  --custom-provider-id mlx-lm \
  --custom-compatibility openai \
  --custom-text-input \
  --accept-risk \
  --skip-health

Run OpenClaw

openclaw agent --local --agent main --message "Hello from Hugging Face"

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. GitHub releases · Usage

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.

Requirements

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

v0.2.2 uses the public Apache-2.0 medmlx-core@v0.1.2 runtime.

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.12 \
  https://github.com/MedMLX/MLX-Reason-CT/releases/download/v0.2.2/mlx_reason_ct-0.2.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.

For an existing Python 3.12 environment, install the same wheel with pip install. For source development, clone the repository and run make env; use uv run mlx-reason-ct for the commands above.

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

Technical details

Inference defaults to FP32 with weights converted directly from the original BF16 checkpoint, without retraining. Implementation and verification details, and the limits of its darwin-arm64 component references are in the companion repository. Upstream model card and limitations.

Intended use

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

License

Downloads last month: 34

MLX

Hardware compatibility

Quantized