Digital Health Clinical Asr Eval

<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

Clinical ASR Flywheel — Stage 3 (Eval)

⚠ Agent: read the Critical Workflow Rules section below before answering. This SKILL.md is self-contained — evals/, references/, and assets/ are pointers, not load-bearing. Answer methodology questions from this file directly; only invoke tools when the user explicitly asks to execute against a real manifest.

You are the score-and-route stage. The user arrives with a NeMo-format manifest.jsonl (either from /digital-health-clinical-asr-build or carried in from elsewhere). You transcribe it via the chosen ASR NIM, score four metrics, produce a five-section leaderboard, and read the decision tree to decide whether the user should advance to /digital-health-clinical-asr-finetune, loop back to /digital-health-clinical-asr-build, or stop and harden the eval.

This skill does not generate audio. If the manifest is missing or empty, send the user back to /digital-health-clinical-asr-build.

Audio leaves your environment — disclose this to the user before any clip is sent

This stage transmits each manifest row's WAV file plus its reference text to an external NVIDIA service. Surface this before invoking the first ASR call:

The clips should be synthetic audio generated by Stage 2 (Magpie TTS over a user-curated term list) — not real patient audio. Do not pass real ASR recordings, real patient encounters, or any PHI through this skill. Scoring then runs locally (pure-Python WER/CER/KER/SER, or jiwer if installed). The scoring step itself does not transmit anything; only the ASR step does.

Critical workflow rules (apply on every activation)

For methodology questions (leaderboard structure, KER definition, decision tree), answer from this file. Don't invoke tools, call other skills, or run scripts unless the user explicitly asks to execute against a real manifest. Surface these facts in any response:

1. Off-ramp first. If the user is asking about something outside scoring, route and stop without running any workflow:
   • ASR model-catalog selection / comparison / alternative NIMs → /riva-asr
   • ASR auth (API keys, bearer tokens, function IDs) → /riva-asr
   • ASR gRPC protocol, streaming, batching, chunking, retries → /riva-asr
   • NIM deploy / riva-build / riva-deploy → /riva-asr-custom
   • NGC / Docker / NVIDIA Container Toolkit → /riva-nim-setup
   • No manifest yet → /digital-health-clinical-asr-build
   • Wants to fine-tune now with a known KER → /digital-health-clinical-asr-finetune
2. Default ASR NIM is nvidia/parakeet-tdt-0.6b-v2 (NVCF function-id d3fe9151-442b-4204-a70d-5fcc597fd610, offline gRPC). Env-var overrides: ASR_MODEL_NAME (leaderboard display name), ASR_NVCF_FUNCTION_ID (swap to a different hosted NIM — e.g. Whisper Large v3 b702f636-… while the Parakeet backend is faulting, or a fine-tuned NIM), ASR_ENDPOINT (self-hosted gRPC; takes precedence). Echo the chosen NIM and the resolved function-id back before spending API credits.
3. ASR transcription is inlined in Step 3b (NVCF gRPC + riva.client.ASRService.offline_recognize, same auth pattern as Stage 1). For deeper protocol/auth questions, alternative NIM catalogs, or self-hosted Riva NIM configuration, defer to /riva-asr.
4. KER is the headline. Per-row check: the flagged term words must appear in order, contiguous, adjacent in the normalized hypothesis. cefazolin → cefa zolin is a miss. Aggregate WER hides clinically dangerous failures; both are reported, KER is the gate.
5. The by-ipa_source split is the most informative single number in the leaderboard. The merriam-webster vs magpie_g2p delta proves the SSML override pipeline is doing real work. Read it aloud to the user.
6. Special-case routing. merriam-webster rows good, magpie_g2p rows bad → pronunciation-coverage gap, not a model gap. Route back to /digital-health-clinical-asr-build Step 2d. Do NOT recommend /digital-health-clinical-asr-finetune as a first response.
7. Five-section leaderboard order. Headline (WER/CER/KER/SER) → KER by entity_category → KER by ipa_source → KER by noise_level → Per-term KER worst-first. The by-ipa_source section is mandatory; it is the proof the SSML pipeline works.

Purpose

Score a clinical-ASR manifest, produce a five-section KER leaderboard, and route the user via the post-eval decision tree. Methodology details (metric definitions, normalization, leaderboard order, special-case routing) live in Critical Workflow Rules above and Instructions below.

When to use this skill

Activate on user phrases like:

• "Score my ASR manifest"
• "What's the KER on Parakeet TDT v2?"
• "Run the eval on cycle-N"
• "Compare two ASR models on the clinical benchmark"
• "Generate the leaderboard"
• "I have a manifest.jsonl, how do I score it?"
• "Why is KER 0.4 when WER is 0.07?"
• "Should we fine-tune?" (this is the eval-side question — the post-eval decision tree lives in this skill)

Literal-keyword non-activation check — if the user's message contains any of authenticate, API key, bearer, function ID, gRPC, streaming, chunking, batching, transcription retry, riva-build, riva-deploy, NIM deploy, NGC, Docker, Container Toolkit, or asks "which ASR model is best" / "compare models" / "vendor differences" — do NOT activate the scoring workflow. Apply Critical Workflow Rule #1 above to route to the right sibling skill and stop. This applies even if the user mentions "KER" or "eval" alongside the keyword.

Prerequisites

• A NeMo-format manifest with the clinical extension fields (term, entity_category, ipa_source, voice_id, noise_level, context_type). The schema is documented in the build skill's references/manifest-schema.md.
• NVIDIA_API_KEY exported (Stage 1 prerequisite still applies).
• nvidia-riva-client + soundfile installed (Stage 1 prerequisite). For self-hosted Riva NIM details, see /riva-asr Option B.
• Audio files actually present on disk — run the audio-existence pre-flight from the manifest-schema reference before spending API credits.

Instructions

3a. Pick the ASR NIM

Default: nvidia/parakeet-tdt-0.6b-v2 via NVCF gRPC (offline), function-id d3fe9151-442b-4204-a70d-5fcc597fd610. NVIDIA's current English ASR recommendation — fastest/cheapest in the catalog, and supported in NeMo's stock SFT recipe so the Stage 3 baseline and a Stage 4 fine-tune ride the same model family.

Three runtime env-var override knobs (ASR_MODEL_NAME for leaderboard display, ASR_NVCF_FUNCTION_ID to swap to a different hosted NIM, ASR_ENDPOINT for self-hosted gRPC) plus the full alternate-NIM catalog (Parakeet TDT 1.1B, Parakeet CTC 1.1B, Whisper Large v3, Nemotron streaming) with function IDs and call-shape notes: references/offline-asr-recipe.md.

Echo the chosen NIM, the resolved function-id, and any env-var overrides to the user before spending API credits. A 200-row manifest on hosted Parakeet TDT v2 is cheap; an accidental run against the wrong model on a 1,000-row manifest is not.

3b. Transcribe

For each row in manifest.jsonl, transcribe audio_filepath and write per_sample.json (one JSON object per row, JSONL or a JSON array — caller's choice):

{
  "audio_filepath": "...",
  "ref": "<row.text>",
  "hyp": "<asr output>",
  "term": "<row.term>",
  "entity_category": "<row.entity_category>",
  "ipa_source": "<row.ipa_source>",
  "voice_id": "<row.voice_id>",
  "noise_level": "<row.noise_level>",
  "context_type": "<row.context_type>"
}

Recipe (full Python in references/offline-asr-recipe.md): transcribe_manifest(api_key, manifest_path, out_path, language_code="en-US") opens an offline gRPC stream to NVCF (or to ASR_ENDPOINT if set for self-hosted Riva), calls riva.client.ASRService.offline_recognize per row — sentences in a clinical manifest are ≤ 30 s so no streaming/batching needed — and writes the JSONL above. Same auth_for shape as the Stage 1 setup smoke test. The agent harness passes api_key explicitly; the recipe reads the three env-var overrides (ASR_NVCF_FUNCTION_ID, ASR_MODEL_NAME, ASR_ENDPOINT) at the top so auditors see the knobs in one place.

Whisper fallback (when Parakeet's NVCF backend faults with CUDA illegal-memory-access from Triton) and self-hosted Riva NIM (ASR_ENDPOINT=localhost:50051) env-var patterns: see references/offline-asr-recipe.md (§Whisper fallback, §Self-hosted Riva NIM).

Resilience knobs deferred to the user. If NVCF returns RESOURCE_EXHAUSTED mid-batch, the loop raises on that row; re-run from the failing row. Streaming/batching/retry-with-backoff are out of scope — see /riva-asr.

3c. Score four metrics

For every row, compute:

Normalization (apply to both ref and hyp before all four metrics):

1. Lowercase.
2. NFKD-normalize (smart quotes → ASCII, etc.).
3. Strip punctuation except hyphen.
4. Collapse whitespace runs to a single space.

Inline scoring recipes — normalize / edit_distance / wer / cer / ker / ser (pure-Python, no jiwer dependency): see references/scoring-recipes.md. Aggregate across rows by taking mean(per-row score) for each metric.

Strict KER — term words must appear in order, adjacent in the normalized hypothesis. This is conservative: cefazolin → cefa zolin counts as a miss. That's the right call clinically — a downstream pharmacy lookup will fail on the misspelled token.

KER does not punish surrounding errors. A row where the term is correct and the rest of the sentence is garbage still scores KER=0; the WER on that row will surface the broader problem separately.