Nv Reason Ct

NV-Reason-CT

Purpose

• Runs the documented nvidia/NV-Reason-CT Hugging Face Transformers path on one user-provided 3D NIfTI CT volume and text prompt.

• Emits result_json with input geometry and hash, anatomy-region selection, response text, runtime identity, dependency versions, and limitations.

• Manifest I/O: inputs are ct_request_or_fixture and optional direct ct_volume; output is result_json on stdout.

• Not for diagnosis, treatment, triage, patient-facing output, or clinical reporting.

Instructions

1. Read skill_manifest.yaml before changing arguments, dependencies, side effects, or validation gates.

2. Run scripts/run_nv_reason_ct.py; do not write replacement inference code or use the Gradio demo for normal runs. Before inference, explain that the selected model and processor contain custom Python code running with the caller's permissions. Review the selected Hub revision or local export and obtain the caller's explicit authorization to load that code; ask if it has not already been granted. Only then pass --trust-model-code. Do not infer this consent from a CT request file, environment setting, cached files, or a successful setup check.

3. After that authorization, hosts exposing a helper may use run_script("scripts/run_nv_reason_ct.py", args=["PATH_TO_CT.nii.gz", "--trust-model-code", "--anatomy-region", "chest", "--prompt", "PROMPT", "--out-dir", "OUT_DIR"]).

4. Inspect stdout JSON and the exit status. Preserve JSON for the caller or eval harness, including partial output on failure; do not redirect it away with >. Successful inference writes only stdout, without creating --out-dir. Exit code 3 means generation hit the token ceiling without EOS: the text is incomplete and the completion gate fails. Only then does the wrapper attempt to create --out-dir and save a unique partial_result_*.json. Only a successful save adds output.partial_json_path and prints the path on stderr. If saving fails, stderr warns to retain stdout; the JSON remains available there without a file path. Input, dependency, and inference errors exit 2 with an error on stderr.

Tool scope: Bash runs the committed wrapper and documented setup commands; Read covers skill files, caller-selected inputs, and model assets; Write covers caller-selected outputs and isolated caches. Env is SkillSpector's environment-capability label for the runtime variables listed below, accessed through shell/Python on hosts without a separate environment tool. These declarations do not authorize unrelated file access, printing authentication values, or changing an existing development environment.

Examples

For the end-to-end example, follow EXAMPLES.md to download the upstream Git LFS volumes into a separate checkout, then run examples/example_1.nii.gz through the wrapper for both chest and abdomen. That scan covers both regions according to the upstream README.

Live inference on a chest CT, after explicit custom-code authorization:

python skills/nv-reason-ct/scripts/run_nv_reason_ct.py PATH_TO_CT.nii.gz \
  --trust-model-code \
  --anatomy-region chest \
  --prompt "write a structured chest CT report" \
  --out-dir runs/nv_reason_ct_case

Require exit 0, runtime.mode == "hf_transformers", runtime.mock == false, nonempty response text, and runtime.truncated_by_max_new_tokens == false. A JSON request may also point to the CT volume; replace volume_path in fixtures/example_request.json with an existing authorized file before running it.

For a complete local model-and-processor export saved by upstream SFT or GRPO:

python skills/nv-reason-ct/scripts/run_nv_reason_ct.py \
  --model ./data/nv_reason_ct_sft_example --check-setup --fail-on-not-ready
python skills/nv-reason-ct/scripts/run_nv_reason_ct.py PATH_TO_CT.nii.gz \
  --model ./data/nv_reason_ct_sft_example --anatomy-region chest --trust-model-code

The directory must contain the full model, custom code, tokenizer, and processor assets, not just adapters or an intermediate optimizer checkpoint. Review local custom code before loading it. Local exports bypass Hub revision resolution and load with local_files_only=True; they record runtime.model_source == "local", an absolute runtime.model path, and null revision/resolved_revision. Keep export content hashes separately: a path is not immutable provenance. Do not pass --revision for local exports; NV_REASON_CT_REVISION is ignored for them. --model-id remains an alias for --model. This does not sandbox custom Python code or validate model compatibility beyond the upstream loading contract.

For an abdominal crop, pass --anatomy-region abdomen. Pass --anatomy-region none only for a manually cropped input; upstream preprocessing then uses a centered crop. Pass --no-thinking for a concise response without thinking output.

The region defaults match upstream inference.py: write a structured chest CT report or write a structured abdominal CT report. To exercise another documented prompt in an engineering check, pass --prompt "full chest CT reasoning analysis" (or the abdominal equivalent), or preserve the caller's focused question verbatim. Supply a scan that actually covers the requested anatomy; the wrapper does not establish that coverage.

Each invocation loads the model and starts a new single-turn conversation. The upstream README also documents model reuse and follow-up history, but this wrapper does not preserve earlier turns. Do not simulate a follow-up by silently discarding history or carry answers between scans. Upstream training JSONL files are not runnable demo fixtures: they contain records but no CT volumes. Use the upstream examples/ volumes or a caller-owned authorized NIfTI scan; do not use reference assistant answers as inference prompts.

Available Scripts

Prerequisites

• Python 3.11+ for the wrapper, a CUDA-capable NVIDIA GPU with bfloat16 support for live inference, and enough memory for the model plus volumetric visual tokens.

• Follow NV-Reason-CT's installation instructions in a fresh environment. The upstream repository owns dependency requirements and compatibility guidance; this skill does not duplicate its requirements file or enforce package-version constraints. Use the upstream inference setup, not the training extras. The wrapper never installs or upgrades packages.

• The manifest inventories required packages, including huggingface-hub for model access. Setup reports package availability and installed versions; the historical environment below is advisory evidence, not an installation prescription. Review the selected environment's dependency security separately.

• Model assets may download from https://huggingface.co under ~/.cache/huggingface/. Set HF_TOKEN when repository access requires authentication.

• The upstream examples are available from the public NV-Reason-CT repository and require Git LFS. Download actual volumes with git lfs pull; a small text pointer named .nii.gz is not a CT image. Do not install Git LFS globally or change an existing checkout's configuration without authorization; the example guide uses checkout-local configuration.

• Run a read-only setup check before downloading weights or starting inference. It checks the NV-Reason-CT processor/code assets and all indexed weight shards in only the selected cached Hub snapshot or local export. This is offline file-presence inspection, without model initialization or integrity verification. Other model layouts may require different assets:

python skills/nv-reason-ct/scripts/run_nv_reason_ct.py --check-setup

This diagnostic command exits 0 when it produces a report, even if setup is not ready. For an automation gate after staging model assets, use --check-setup --fail-on-not-ready: exit 0 means ready_for_live_cuda_inference, exit 1 means setup is not ready, and exit 2 means an argument or execution error. Inspect the JSON recommendation in either mode. Readiness covers imports, CUDA/bfloat16, and asset presence, not package-version compatibility or a vulnerability audit; version_constraints_checked is false. Enable offline settings only after the selected model assets and custom code are cached.

Inference without --trust-model-code exits 2 before model lookup or loading. With it, the wrapper warns on stderr before loading custom code, including the resolved Hub commit or local export path. This flag is an acknowledgement, not a sandbox, code audit, or signature verification. The setup report's model_code_opt_in_required remains true even when assets are ready. The manifest's default command does not supply consent; use the documented explicit CLI invocation for authorized live inference.

For a disposable run, keep caches separate from installed packages: set HF_HOME, HF_HUB_CACHE, HF_MODULES_CACHE, XDG_CACHE_HOME, and TORCH_HOME to subdirectories of a caller-owned temporary directory before launching Python. After the process exits, remove only those explicitly identified task caches when cleanup is requested, retaining input scans and result JSON. Do not purge a shared Hugging Face cache or change an existing development environment.

Verified environment baseline

The live CUDA path was reverified on 2026-09-21 with the upstream examples/example_1.nii.gz in both chest and abdomen modes, using the versions below. These are recorded successful-run settings, not required versions, an upstream compatibility guarantee, or a security recommendation. Select the environment using upstream guidance and a PyTorch CUDA build compatible with the host driver; the recorded PyTorch distribution version was 2.12.0, and torch.__version__ reported 2.12.0+cu130.

The historical Transformers version below is affected by CVE-2026-9856. Consult upstream maintainers for a compatible, security-reviewed environment; this skill has not verified a remediated live baseline. Moving dependency ownership upstream does not resolve that finding.

The verified inference settings were one 48 GB NVIDIA RTX 6000 Ada GPU (driver 580.178.04), bfloat16 model weights, SDPA attention, deterministic decoding (do_sample=False), thinking enabled, and max_new_tokens=2048. The upstream example generated 438 tokens with the chest crop and 453 with the abdomen crop; neither response was truncated. Both matched the upstream CLI after trimming surrounding whitespace, using the same reviewed immutable model revision and offline assets in a disposable environment. All three upstream volumes also passed input/geometry/hash checks. This is a recorded baseline, not a fresh run of every subsequent skill revision. It verifies inference wiring, not clinical correctness. Lower-memory GPUs and other PyTorch/CUDA combinations have not yet been verified by this skill.

Environment variables:

Inference uses the upstream contract: AutoModelForImageTextToText and AutoProcessor with trust_remote_code=True, bfloat16, SDPA attention, images3d=[CT_PATH], deterministic generation, and anatomy-aware chest or abdomen cropping. For Hub models, each run resolves the requested revision once and uses that immutable commit for model weights, processor assets, and custom code. Output records runtime.model_source == "hub", retains the requested runtime.revision, and records the commit in runtime.resolved_revision. Keep private revision identifiers in local evidence until approved for disclosure. CUDA is always required; select a GPU with CUDA_VISIBLE_DEVICES.

Limitations

• The wrapper loads upstream custom code only after explicit --trust-model-code opt-in. Review that code and use an isolated environment and an immutable reviewed revision for evidence runs. Neither offline mode nor a local export prevents arbitrary actions by custom code.

• It checks readable 3D NIfTI structure, positive voxel spacing, a finite affine, and file identity. It does not verify de-identification, Hounsfield-unit calibration, anatomy coverage, crop quality, or clinical correctness.

• Model output can hallucinate, omit findings, or present unreliable reasoning. Reviewable reasoning text is generated output, not proof of the model's internal computation.

• CT scans and model weights must be supplied separately. The upstream examples demonstrate inference wiring and provide no clinical ground truth. A successful setup check is not completed model inference.

• The moving main revision is suitable only for development. Replace it with the reviewed immutable public release revision before publication.

• This wrapper does not cover the Gradio UI, finetuning, retraining, clinical deployment, or patient-facing use.

Troubleshooting

License

This skill's documentation, wrapper, and tests are licensed under Apache-2.0. See LICENSE for the full terms.

The separately obtained upstream NV-Reason-CT model code, weights, and example data retain their upstream terms, including OpenMDW-1.1. The skill's Apache-2.0 license does not relicense those assets. Retain the applicable licenses and notices when redistributing either the skill or upstream materials.