Nv Segment Ct Agent Skill

NV-Segment-CT

Purpose

• Used for running NV-Segment-CT VISTA3D on CT NIfTI volumes and recording label-map evidence. Not for clinical interpretation.
• Use the wrapper exactly as documented; do not replace the upstream entrypoint with a handwritten implementation.
• Manifest I/O: inputs are ct_volume; outputs are label_map and result_json.

Instructions

• Read skill_manifest.yaml before changing arguments, side effects, or validation gates.
• Run scripts/run_vista3d.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_vista3d.py", args=[...]); otherwise run the Bash/Python command shown below.
• Create the documented Python 3.10 virtual environment and invoke its binaries directly; do not install model dependencies into the caller's active environment.
• Check the emitted JSON and paired verifier guidance before treating the run as evidence.

Available Scripts

| Script | Purpose | Arguments |

|---|---|---|

| scripts/run_vista3d.py | Primary entrypoint declared by skill_manifest.yaml. | PATH_TO_CT.nii.gz [--output-dir OUT_DIR] [--label-prompts IDS] |

Prerequisites

• Runtime requirements: Python 3.10 with venv support and GPU/CUDA when declared by the manifest. Model packages come from the pinned upstream requirements file; only wrapper-specific packages are added locally.
• Side effects: creates an isolated environment under

~/.cache/nvidia-skills/venvs/nv-segment-ct-f9f5f51/, writes the downloaded

bundle under skills/nv-segment-ct/bundle/, may cache model assets under

~/.cache/huggingface/, and may contact https://huggingface.co and

https://raw.githubusercontent.com during first setup; the optional spleen

fixture fetcher downloads MSD09 from

https://msd-for-monai.s3-us-west-2.amazonaws.com.

• Run commands from the repository root unless an existing section below says otherwise.

Limitations

• This is a thin wrapper. Inference, preprocessing, and postprocessing are delegated entirely to the official hugging_face_pipeline.HuggingFacePipelineHelper in bundle/. Do not modify code under bundle/.
• transformers==4.46.3 is the wrapper compatibility overlay tested with the upstream requirements' Torch 2.0.1; newer Transformers releases can disable that older Torch backend.
• The pinned upstream requirements include Torch 2.0.1. Use only the pinned NVIDIA model assets; do not load untrusted checkpoints in this legacy reproduction environment.
• Device auto-detected (cuda if available, else cpu); --device flag overrides.
• Output may be schema-valid but semantically empty (e.g. label prompts that do not match the input anatomy). Sanity gates assert at least one foreground voxel per requested anatomy.
• Not for clinical deployment, clinical interpretation, autonomous diagnosis, regulatory submission.

Troubleshooting

| Error | Cause | Fix |

|---|---|---|

| ensurepip is not available while creating the environment | The host Python installation omitted its OS venv package. | Install the matching Python 3.10 venv support package or create the same isolated environment with virtualenv -p python3.10. |

| 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/NV-Segment-CT helper. The wrapper does not

reimplement VISTA3D inference.

Exact Runnable Surface

For CT segmentation user runs, use this repo-root wrapper path exactly:

"$NV_SEGMENT_CT_VENV/bin/python" skills/nv-segment-ct/scripts/run_vista3d.py PATH_TO_CT.nii.gz --label-prompts "1,3,5,14" --output-dir OUT_DIR

Do not invent infer.py, Medical AI Skills run, python -m nv_segment_ct, or anatomy-name-only flags. For spleen, liver, right kidney, and left kidney, the required VISTA3D label IDs are exactly 1,3,5,14.

Preconditions

The skill assumes a Python 3.10 interpreter with venv support. Its documented

command creates a dedicated environment and installs the model dependencies

from NV-Segment-CT/requirements.txt at the immutable NVIDIA-Medtech commit

f9f5f51b589e5dc9c23c453cf5138398e4084056. The Hugging Face bundle itself

does not ship a requirements.txt.

Two one-time downloads (the documented command does the first one; the

fixture fetch is a separate step you run when bootstrapping):

# Spleen example fixture from Decathlon MSD09 (~1.5 GB tar, ~11 MB
# fixture extracted into skills/nv-segment-ct/fixtures/spleen_03.nii.gz):
python skills/nv-segment-ct/fixtures/fetch_spleen_fixture.py

Both downloads (the bundle below, and the fixture) are gitignored

(Medical AI Skills policy: no medical data or model weights in git). The fetch

script is idempotent and caches the tar under

.workbench_data/datasets/ so re-runs are no-ops.

Runtime needs an NVIDIA GPU with CUDA. CPU fallback is supported but slow.

Usage

From the skills repository root, run the complete bootstrap. Invoke the virtual

environment's binaries directly so the caller's active environment is not

modified:

export NV_SEGMENT_CT_VENV="${NV_SEGMENT_CT_VENV:-$HOME/.cache/nvidia-skills/venvs/nv-segment-ct-f9f5f51}"
export NV_SEGMENT_CT_REQUIREMENTS="${NV_SEGMENT_CT_REQUIREMENTS:-https://raw.githubusercontent.com/NVIDIA-Medtech/NV-Segment-CTMR/f9f5f51b589e5dc9c23c453cf5138398e4084056/NV-Segment-CT/requirements.txt}"

if [ ! -x "$NV_SEGMENT_CT_VENV/bin/python" ]; then
  python3.10 -m venv "$NV_SEGMENT_CT_VENV"
fi

"$NV_SEGMENT_CT_VENV/bin/python" -m pip install \
  -r "$NV_SEGMENT_CT_REQUIREMENTS" \
  "transformers==4.46.3" \
  "typer>=0.9"

"$NV_SEGMENT_CT_VENV/bin/hf" download nvidia/NV-Segment-CT \
  --revision afb51518689f71e6abb367ee6301b2cd0225c66a \
  --local-dir skills/nv-segment-ct/bundle/

"$NV_SEGMENT_CT_VENV/bin/python" skills/nv-segment-ct/scripts/run_vista3d.py PATH_TO_CT.nii.gz \
  --label-prompts "1,3,5,14" \
  --output-dir vista3d_outputs

When the user names anatomies, translate them to VISTA3D class IDs before

running. For the common abdominal CT request:

| Anatomy | VISTA3D class ID |

|---|---:|

| liver | 1 |

| spleen | 3 |

| right kidney | 5 |

| left kidney | 14 |

For "segment the spleen, liver, right kidney, and left kidney", the correct

--label-prompts value is exactly "1,3,5,14". Do not substitute kidney

IDs from another label dictionary; the wrapper validates the requested label

set and will mark the run invalid if the emitted mask contains labels outside

the requested set.

The install and download steps are load-bearing. The pinned upstream file owns

the model environment, while Transformers and Typer support this thin wrapper.

hf download pulls the ~832 MB model bundle into

skills/nv-segment-ct/bundle/; subsequent calls reuse the caches.

label-prompts are VISTA3D class IDs. The evidence output records input

geometry, output mask path, observed label IDs, unexpected labels,

per-class voxel counts, per-class physical volumes computed from the output

mask header spacing, runtime, model identity, and fixed code-derived artifact

checks such as mask shape, affine match, label set, foreground count, and

class-volume bounds.

Pass --ground-truth PATH to record a reference label-map path under

input.ground_truth_path. The skill does not compute Dice; that is the

paired verifier's job.

Anatomy plausibility (per-class volume bounds, fragmentation, bilateral

symmetry, liver larger than spleen) and optional per-class Dice/IoU against

the recorded ground truth are checked by

verifiers/ct_segmentation_quality_v1.

Not for clinical interpretation, production deployment, or non-CT modalities.