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.