nv-reason-cxr

Files (10)

• BENCHMARK.md
• SKILL.md
• evals.json · evals/
• synthetic_cxr_input.json · fixtures/
• run_nv_reason_cxr.py · scripts/
• skill-card.md
• skill.oms.sig
• skill_manifest.yaml
• test_nv_reason_cxr.py · tests/
• output_schema.json · validators/

SKILL.md (first lines)

# NV-Reason-CXR

## Purpose
- Used for command-shape or live NV-Reason-CXR chest X-ray reasoning smoke tests. Not for diagnosis or clinical reporting.
- Use the wrapper exactly as documented; do not replace the upstream entrypoint with a handwritten implementation.
- Manifest I/O: inputs are `chest_xray_image_or_fixture`; outputs are `result_json`.

## Instructions
- Read `skill_manifest.yaml` before changing arguments, side effects, or validation gates.
- Run `scripts/run_nv_reason_cxr.py` through the documented command below; pass `--out-dir` only for generated fixtures or harness-managed artifact directories.
- If a host agent exposes `run_script`, use `run_script("scripts/run_nv_reason_cxr.py", args=[...])`; otherwise run the Bash/Python command shown below.
- Check the emitted JSON and paired verifier guidance before treating the run as evidence.
- When reporting a completed run, return the full wrapper JSON or at minimum
  the complete `output.response_text` exactly as emitted, including any
  model-generated `<think>...</think>` and `<answer>...</answer>` sections. Do
  not collapse the result to labels unless the user explicitly asks for a
  summary.

## Available Scripts
| Script | Purpose | Arguments |
|---|---|---|
| `scripts/run_nv_reason_cxr.py` | Primary entrypoint declared by skill_manifest.yaml. | `PATH_TO_CXR_OR_FIXTURE [--out-dir OUT_DIR] [--backend local\|hf-space-api] [--mock] [--check-setup]` |

## Prerequisites
- Local backend requirements: GPU/CUDA when declared by the manifest; Python packages listed in `runtime.side_effects.pip_packages`.
- API backend requirements: public network access to the [Hugging Face Space](https://huggingface.co/spaces/nvidia/nv-reason-cxr); no local PyTorch, Transformers, CUDA, model cache, or Hugging Face token.
- Side effects: emits result JSON on stdout; may write generated fixture artifacts under the caller's `--out-dir`; may cache model assets under `~/.cache/huggingface/` for local inference; and may contact `https://huggingface.co`, `https://github.com`, or `https://*.hf.space` outside `--mock` mode.
- Run commands from the repository root unless an existing section below says otherwise.

## Limitations
- This is a thin wrapper. Image preprocessing, model inference, and decoding are delegated to Hugging Face Transformers and the NV-Reason-CXR-3B model.
- Output is not a diagnosis, clinical report, treatment recommendation, or triage decision. It is engineering evidence and must be reviewed by a qualified professional before any medical use.
- The model may hallucinate findings, miss subtle abnormalities, misread support devices, or produce overconfident prose.
- The committed fixture uses a generated synthetic PNG and deterministic mock response so CI can verify wrapper behavior without downloading model weights. Mock mode is not a substitute for model inference.
- The `hf-space-api` backend depends on public Hugging Face Space availability and API compatibility.
- Not for clinical deployment, clinical interpretation, autonomous diagnosis, treatment decisions.

## 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. |
| CUDA unavailable from an agent but available in a user terminal | The agent sandbox, container, or job wrapper may not expose NVIDIA device nodes even when the same Python environment has CUDA-capable PyTorch installed. | Compare `python -c "import torch; print(torch.cuda.is_available())"` and `nvidia-smi` inside the agent context and in the user terminal. If only the agent context fails, rerun with GPU/device access, use the host terminal, or pass `--device cpu --allow-cpu` only for an explicit slow CPU test. |
| API backend HTTP or schema error | The public Hugging Face Space may be unavailable, rate limited, or changed. | Re-run later or use `--backend local` when local dependencies and CUDA are available. |
| 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. |

Runs NVIDIA-Medtech [`NV-Reason-CXR-3B`](https://github.com/NVIDIA-Medtech/NV-Reason-CXR/tree/83a4d51c9fbbff68156a5f01796f04e26519b6ad)
for chest X-ray image interpretation through either the documented local
Hugging Face Transformers inference path or the public Hugging Face Space API.
The wrapper does not reimplement the model, image preprocessing, or decoding.


## Exact Runnable Surface

For command-shape smoke tests and JSON fixtures, use this repo-root wrapper path exactly:

```bash
python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR_OR_FIXTURE --mock --out-dir OUT_DIR
```

For local live image inference, omit `--mock` only when the user asks for live
model inference. Local is the default backend:

```bash
python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR_OR_FIXTURE \
  --prompt "Find abnormalities and support devices." \
  --backend local
```

For public API inference without local model packages, use:

```bash
python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR_OR_FIXTURE \
  --prompt "Find abnormalities and support devices." \
  --backend hf-space-api
```

Do not invent `Medical AI Skills run`, `eval_engine/run.py`, `infer.py`, or
`python -m nv_reason_cxr` commands for ordinary user runs.

## Preconditions

For `--backend local`, install the inference dependencies in the environment
that will run the skill:

```bash
pip install torch==2.7.1 torchvision==0.22.1 transformers==4.56.1 Pillow
```

The model weights and remote model code are loaded from
`nvidia/NV-Reason-CXR-3B` revision
`056bd0383b35226554da9dc5866e095df174ae19` through Transformers. They may
download to the Hugging Face cache on first use.
Set `TRANSFORMERS_OFFLINE=1` or pass `--local-files-only` only after the
weights are already cached.

CUDA is expected for practical inference. CPU execution may work for small
tests but is slow and must be requested explicitly.

For `--backend hf-space-api`, no local PyTorch, Transformers, CUDA, model
cache, or Hugging Face token is required. The backend sends the image and
prompt to the public `nvidia/nv-reason-cxr` Hugging Face Space.

Check the local environment before downloading weights or running inference:

```bash
python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py --check-setup
```

The setup report checks importable dependencies, CUDA visibility, Hugging Face
cache state, and the recommended next step.

Operational environment variables:

| Variable | When to use |
|---|---|
| `MOCK_NV_REASON_CXR` | Set to `1` for deterministic command-shape smoke tests without model inference. |
| `NV_REASON_CXR_MODEL` | Override the Hugging Face model id only for compatibility probes. |
| `HF_HOME` | Point at a pre-populated Hugging Face cache. |

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills