nv-generate-mr-brain — Claude Code skill: how to install

---
name: nv-generate-mr-brain
description: Used for generating synthetic T1, T2, FLAIR, SWI, or MRA brain MRI volumes with NV-Generate-CTMR MR-Brain v1. Not for production training data.
license: Apache-2.0
allowed-tools: Bash, Read, Write, WebFetch, Env
permissions: [env, file_read, file_write, network, shell]
metadata:
  author: 'NVIDIA MedTech Team'
  tags:
    - MedTech
    - MRI
    - brain
---

# NV-Generate-MR-Brain

## Purpose
- Used for generating synthetic T1, T2, FLAIR, SWI, or MRA brain MRI volumes with NV-Generate-CTMR rflow-mr-brain v1. Not for production training data.
- Use the wrapper exactly as documented; do not replace the upstream entrypoint with a handwritten implementation.
- Do not write custom inference code for normal runs. The wrapper owns config staging, output paths, and validation.
- Manifest I/O: inputs are `model_config_override`; outputs are `synthetic_mr_brain_volumes` and `result_json`.

## Instructions
- Read `skill_manifest.yaml` before changing arguments, side effects, or validation gates.
- Run `scripts/run_mr_brain.py` through the documented command below; keep outputs under a caller-provided run directory.
- If a host agent exposes `run_script`, use `run_script("scripts/run_mr_brain.py", args=[...])`; otherwise run the Bash/Python command shown below.
- For a command-shape review, do not install packages, clone repositories,
  download weights, or start GPU inference. Emit only the exact wrapper command
  with the supplied config path plus explicit `--output-dir`, `--modality`, and
  `--random-seed` values.
- For an executable run, emit a single bash code block and keep the
  `python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt"` step in that
  same command — the runtime may be a fresh environment without
  `nibabel`/MONAI, so dropping the install fails with `ModuleNotFoundError`.
- If `--modality mri_mra` is selected, state that upstream reports sparse MRA
  training coverage and that output quality is not guaranteed.
- Do not add `rm`, `mkdir`, or any cleanup of `--output-dir`; the wrapper creates it. Use a fresh `--output-dir` instead of deleting one.
- Check the emitted JSON and paired verifier guidance before treating the run as evidence.

## Examples

Command-shape review only (no setup or execution):

```bash
python skills/nv-generate-mr-brain/scripts/run_mr_brain.py \
  PATH_TO_MR_BRAIN_CONFIG.json \
  --output-dir runs/nv_generate_mr_brain_demo \
  --modality mri_t1 \
  --random-seed 1234
```

For an executable run, use the setup-aware command under
[Usage](#usage).

## Available Scripts
| Script | Purpose | Arguments |
|---|---|---|
| `scripts/run_mr_brain.py` | Primary entrypoint declared by skill_manifest.yaml. | `MODEL_CONFIG.json --output-dir OUT_DIR --modality mri_t1 [--random-seed N] [--yes]` |

## Prerequisites
- Runtime requirements: GPU/CUDA when declared by the manifest; Python packages listed in `runtime.side_effects.pip_packages`.
- Side effects: writes generated outputs under the caller's `--output-dir`, may cache model assets under `~/.cache/huggingface/`, and may contact `https://huggingface.co` or `https://github.com` during setup.
- Run commands from the repository root unless an existing section below says otherwise.

## Limitations
- This is a thin wrapper. Inference, sampling, and decoding are delegated entirely to NVIDIA-Medtech/NV-Generate-CTMR's `scripts.diff_model_infer`. Do not modify code under $NV_GENERATE_ROOT or the repo-local fallback at .workbench_data/upstreams/NV-Generate-CTMR.
- rflow-mr-brain generates image-only synthetic brain MRI volumes. It does not emit paired segmentation masks.
- Output volumes are synthetic. They are not safe as training data for production medtech models without independent quality review.
- Not for clinical deployment, clinical interpretation, autonomous diagnosis, regulatory submission.

## Troubleshooting
| Error | Cause | Fix |
|---|---|---|
| Missing dependency or import error | Runtime package drift from `skill_manifest.yaml`. | Install the packages declared in the manifest or use the documented setup command. |
| Empty or schema-invalid output | Wrong input path, unsupported modality, or upstream failure. | Re-run with a known fixture and inspect the wrapper JSON plus stderr. |
| Validation gate failure | Output violated a declared engineering invariant. | Keep the failed evidence pack and use the gate message to repair inputs or wrapper code. |

Wraps the upstream
[`NVIDIA-Medtech/NV-Generate-CTMR`](https://github.com/NVIDIA-Medtech/NV-Generate-CTMR/tree/da438fec6484cdb6f421f8c7051d954ebefff730)
MR brain image-only generation workflow. The wrapper does not reimplement
diffusion sampling or autoencoder decoding. It stages config overrides, runs
the documented `python -m scripts.diff_model_infer` command for
`rflow-mr-brain`, then summarizes the generated NIfTI volume.


## Exact Runnable Surface

For user run commands, use this repo-root wrapper path exactly:

```bash
export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr-brain/scripts/run_mr_brain.py PATH_TO_MR_BRAIN_CONFIG.json --output-dir OUT_DIR --modality mri_t1 --random-seed 1234
```

Do not invent `generate.sh`, `infer.py`, `Medical AI Skills run`, or `python -m nv_generate_mr_brain` commands. `PATH_TO_MR_BRAIN_CONFIG.json` must be the user's supplied request path.

## Preconditions

If `NV_GENERATE_ROOT` already names a local checkout, the wrapper uses it and
records its current commit in the result. Otherwise, create the recommended
pinned default checkout once:

```bash
if [ -z "${NV_GENERATE_ROOT:-}" ]; then
  export NV_GENERATE_COMMIT=da438fec6484cdb6f421f8c7051d954ebefff730
  export NV_GENERATE_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe"
  if [ ! -d "$NV_GENERATE_ROOT/.git" ]; then
    git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git "$NV_GENERATE_ROOT"
    git -C "$NV_GENERATE_ROOT" checkout --detach "$NV_GENERATE_COMMIT"
  fi
fi
pip install -r "$NV_GENERATE_ROOT/requirements.txt"
```

The wrapper executes upstream code only when `NV_GENERATE_ROOT` is at the exact
manifest commit and its tracked files are clean. Keep model weights untracked
under `models/`, and use the wrapper override JSON instead of editing upstream
configs. Child processes receive only an allowlist of runtime, CUDA, locale,
and certificate variables; API keys, tokens, passwords, and unrelated parent
environment values are not forwarded.

Download the reused autoencoder and MR-Brain v1 checkpoint from their exact
manifest revisions:

```bash
python -m huggingface_hub.commands.huggingface_cli download \
  nvidia/NV-Generate-CT models/autoencoder_v1.pt \
  --revision 75ac080fb1083c403793563477724c038e7d430c \
  --local-dir "$NV_GENERATE_ROOT"
python -m huggingface_hub.commands.huggingface_cli download \
  nvidia/NV-Generate-MR-Brain models/diff_unet_3d_rflow-mr-brain_v1.pt \
  --revision ef9759bf221265b2704569cdeeac20bbf03b62ee \
  --local-dir "$NV_GENERATE_ROOT"
```

The wrapper verifies both downloaded files against their published Git LFS
SHA-256 object IDs before launching inference.

Runtime needs an NVIDIA GPU with at least 16 GB VRAM. There is no CPU
fallback in the upstream path.

The wrapper also searches `.workbench_data/upstreams/NV-Generate-CTMR` if
`NV_GENERATE_ROOT` is unset or does not have the required upstream layout.

For agent-generated user run commands, use the command in Usage. Do not prepend
clone or model-download setup steps when the repo-local
upstream cache already exists. In a fresh Python environment, still include
`pip install -r "$NV_GENERATE_ROOT/requirements.txt"` before the wrapper unless
the active environment has already proven those imports are available; cached
weights do not imply cached Python packages. If setup requires `cd "$NV_GENERATE_ROOT"`, return to the Medical AI Skills repo before invoking
`skills/nv-generate-mr-brain/scripts/run_mr_brain.py`.

## Usage

```bash
export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr-brain/scripts/run_mr_brain.py \
  PATH_TO_MR_BRAIN_CONFIG.json \
  --output-dir runs/nv_generate_mr_brain_demo \
  --modality mri_t1 \
  --random-seed 1234
```

Replace `PATH_TO_MR_BRAIN_CONFIG.json` with the user's actual request/config
path. Do not copy the fixture path from this document unless the user
explicitly asked to run that fixture. If the user says "the request is at
`runs/.../default_mri_t1.json`", that exact path is the first positional
argument to `scripts/run_mr_brain.py`.

Supported MR-brain modality names are `mri`, `mri_t1`, `mri_t2`,
`mri_flair`, `mri_mra`, `mri_swi`, `mri_t1_skull_stripped`,
`mri_t2_skull_stripped`, `mri_flair_skull_stripped`,
`mri_mra_skull_stripped`, and `mri_swi_skull_stripped`. These map to the upstream
`configs/modality_mapping.json` IDs documented in the README.
For FOV and setup details, see `references/fov-and-downloads.md`.

The pinned v1 config ships axial T1w defaults of `dim=[256,256,128]`,
`spacing=[0.94,0.94,1.36]`, 30 inference steps, and
`cfg_guidance_scale=2`. Keep the staged config value unless a model-specific
validation justifies an override; older examples may describe the v0
`256^3`/1 mm geometry or guidance scale 10. MRA is supported by v1, but the
upstream training-data report contains few MRA scans, so output quality is not
guaranteed.

The fixture argument is a small JSON override for
`configs/config_maisi_diff_model_rflow-mr-brain.json`. Pass `default` to use
the upstream defaults plus the CLI modality and random seed. Common override
keys are `dim`, `spacing`, `num_inference_steps`, `cfg_guidance_scale`, and
`modality`.

Each run records the staged config, model inventory, upstream command, output
geometry, spacing, affine, intensity range, and non-constant / finite-data
checks. Output volumes are synthetic and are not safe as production training
data without independent review.

Not for clinical interpretation, production deployment, autonomous diagnosis,
or regulatory submission.