# Medsegagent Nnunet Runner

> Inspect `nnUNet_results`, choose a deployed nnUNet task, and run or prepare segmentation inference. Use when a user wants to match a free-form target to deployed labels, select the right task, or run prediction and postprocessing. Use when this capability is needed.

- Skill: `tomevault-io/medsegagent-nnunet-runner` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/medsegagent-nnunet-runner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/medsegagent-nnunet-runner/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/medsegagent-nnunet-runner

---


# nnUNet Segmentation Runner

## Overview

Inspect what is deployed, choose the right nnUNet task, and run or prepare inference. Do not claim inference succeeded unless it was actually run and outputs were produced.

## Prerequisites

- An nnUNet v2 environment is available.
- `nnUNet_results` is configured. `nnUNet_raw` and `nnUNet_preprocessed` may also be needed.
- To actually run inference, the nnUNet CLI or Python API must be installed and usable.
- Custom trainers must be importable in the target environment.

## Workflow

1. Inspect the nnUNet environment first.
   - Prefer `nnUNet_results`.
   - Use `RESULTS_FOLDER` only as a legacy fallback.
   - If the environment is unclear, run `scripts/nnunetv2-doctor.sh` first.
   - Run `scripts/list_nnunet_results.py --json` to enumerate real datasets, model folders, modalities, labels, folds, and checkpoints.

2. Parse the request into:
   - modality
   - target
   - qualifiers such as left/right, tumor/cyst, whole organ vs substructure

3. Read metadata in this order:
   - `dataset.json` under nnUNet result folders for what is actually available
   - `dataset/*.json` in this repo for supplemental routing metadata
   - `dataset/README.md` only when adding or fixing dataset entries

4. Filter by modality, then match labels conservatively.
   - Preserve laterality and substructure specificity.
   - Keep tumor, cyst, lesion, vessel, and organ concepts separate.
   - Treat repo metadata as secondary when it disagrees with deployed nnUNet results.

5. Choose how to run inference.
   - Prefer `inference_instructions.txt` when it exists.
   - For default model folders, use `nnUNetv2_predict`, plus ensembling or postprocessing if needed.
   - For custom trainers, prefer exact model-folder inference through the Python predictor API.
   - Use all available trained folds by default unless the environment only supports a specific fold such as `all`.
   - Keep input naming and file endings consistent with the selected task `dataset.json`.

6. Return either:
   - a compact dataset-to-label mapping
   - or the selected task plus the exact inference command

```json
{
  "DatasetNameA": [1, 2],
  "DatasetNameB": [7]
}
```

Return `{}` if no suitable modality or label is available, and say why.

## Rules

- Prefer real nnUNet availability over paper claims or static repo metadata.
- If a dataset exists in repo metadata but not in `nnUNet_results`, describe it as known but not deployed.
- Group multiple trainer folders under one dataset unless the user explicitly asks about checkpoints or trainer variants.
- Prefer officially generated `inference_instructions.txt` when present.
- If input files do not match the trained task modality, naming scheme, or file ending, stop and say the input is not ready.
- Do not silently guess a configuration when multiple materially different deployed options exist.
- If repo metadata and nnUNet metadata disagree, report the mismatch explicitly.
- Do not guess custom trainer or plans settings from memory; read them from the selected model folder.

## Extending Coverage

When adding or updating routing metadata:

1. Follow `dataset/README.md`.
2. Keep names explicit, such as `kidney_left`.
3. Do not invent deployed availability if no trained output exists in `nnUNet_results`.

## References

- Read `references/nnunetv2.md` only when you need the official nnUNet v2 path conventions, result layout, prediction commands, or `dataset.json` details.
- Read `references/examples.md` only when you need compact routing or inference examples.

---
> Source: [uni-medical/MedSegAgent](https://github.com/uni-medical/MedSegAgent) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-19 -->