Phase 2: Visit scribe auto-fills GAD-7 / PHQ-9

[goelalex]

Summary

Phase 2 of the six-phase refresh. During a visit, a clinician captures a transcript — dictated (browser mic → PhenoML transcribe API) or pasted — and the scribe-fill bot pre-fills GAD-7 and PHQ-9 with scored answers. The clinician reviews/edits the answers in editable QuestionnaireForms and saves each as a QuestionnaireResponse linked to the encounter. Mirrors the Phase 1 review-before-persist pattern; nothing is saved until the clinician clicks Save.

QuestionnaireResponse conformance (profile-driven)

Rather than prompt-stuffing the whole Questionnaire and hand-reconciling the model's answers, scribe-fill now uses a "build a QR profile, then conform outputs to it" flow:

1. src/bots/buildProfile.ts — deterministic, pure, server-only (no LLM). buildQuestionnaireResponseProfile(questionnaire) walks the item tree (recursing into groups, skipping group/display) and synthesizes a StructureDefinition that profiles QuestionnaireResponse: item sliced with discriminator = pattern on linkId / rules: "open", each answerable leaf getting a fixed linkId/text, a constrained answer.value[x] (mapped from the item type via valueTypesFor — boolean→boolean, choice+coding→Coding, …), and a required binding whose description carries the allowed codes (codesDescription). min:0 everywhere so the model is never forced to fabricate an answer. Profile id is content-derived — qr-<title-slug>-<sha256(items)[:8]> — so rebuilding the same form yields the same id (idempotent). Also exports composeExtractionText (the compact "question key" — - [linkId] text (type; allowed codes) — inlined ahead of the transcript).
2. Cache in Medplum on the fly. The bot looks the profile up by its canonical url; if no profile matches deterministically, it createResources the StructureDefinition into Medplum so it's cached and inspectable.
3. Register with PhenoML. The profile is base64-encoded and uploaded via lang2Fhir.uploadProfile into the medplum_questionnaires implementation guide (once per warm session; a "profile already exists" response is treated as success).
4. Conform via lang2fhir. lang2Fhir.create({ resource: <profileId>, text }) targets the custom profile so the returned resource conforms to it. Falls back to the generic questionnaireresponse profile (same text) if the custom profile can't be used (e.g. an account tier without custom profiles), so the flow always returns a usable response.
5. src/bots/postValidate.ts — treat LLM output as untrusted. Guards the resourceType, compares each answer against the deterministic question map and collects warnings (codes outside the allowed set, invented linkIds, type mismatches — tolerating valueString flex / numeric-as-Quantity), normalizes a matched code onto the canonical answerOption Coding (so the Medplum QuestionnaireForm renders and scores it), and stamps the FHIR-required fields (status, authored, questionnaire, subject, encounter). It does not rebuild from the form or invent answers — unmatched items are left for the clinician to correct in the editable form.

Behavior note: because the profile is min:0 and the prompt says so, questions with no evidence in the transcript are now omitted rather than defaulted to lowest-severity. The bot's input/output contract is unchanged, so the UI is untouched.

What's included

• Seed data — src/data/screening-questionnaires-bundle.json: net-new transaction bundle with GAD-7 / PHQ-9 Questionnaires (LOINC codes, ordinalValue-scored answer options), loaded from Get Started → Import Screening Questionnaires like existing seed data (idempotent via ifNoneExist).
• scribe-fill bot — src/bots/scribe-fill.ts: thin orchestrator over the profile-driven flow above (build → cache in Medplum → uploadProfile → create targeting the profile → postValidate). Does not persist — returns the QR for review. Helpers live in buildProfile.ts / postValidate.ts (co-located under src/bots since bots can't import from src/utils).
• voice-transcribe bot — src/bots/voice-transcribe.ts: transcription uses the PhenoML voice API (client.voice.voice.transcribe, https://developer.pheno.ml/reference/transcribe) instead of an in-browser model. PhenoML credentials must stay server-side, so the browser posts the recorded audio (base64) to this bot, which returns { transcript }. The @huggingface/transformers browser-Whisper dependency has been removed.
• Reusable dictation — ScribeTextarea (src/components/ScribeTextarea.tsx): a Mantine Textarea with a built-in mic (backed by useScribeTranscription). Dropped onto any free text box — the chart note, the screening transcript, and the lang2fhir create page.
• UI — the screening scribe lives inside the "Note & Tasks" tab (ScribePanel, not a separate tab): transcript capture (dictate or paste) → Generate → editable forms with a live score badge → Save to encounter.
• Shared pieces for Phases 3–6 — useScribeTranscription hook, executeBotByName helper, screening.ts (canonical URLs + scoreQuestionnaireResponse), and the deterministic buildProfile.ts profile builder.
• Bots — both new bots are registered in deploy-bots.ts. All PhenoML bots use PHENOML_CLIENT_ID / PHENOML_CLIENT_SECRET / optional PHENOML_BASE_URL (not EMAIL/PASSWORD).
• Tests — screening scoring, executeBotByName, voice-transcribe, the end-to-end ScribePanel flow, and the profile-driven path with the PhenoML SDK mocked: buildProfile (deterministic id, slice/binding/value-type generation, question key), postValidate (code enrichment, warnings, guards), and scribe-fill (profile build → Medplum cache-on-the-fly → upload dedup/"already exists" tolerance → create targeting the profile → generic fallback).

Automated checks

• npx vitest run — all new/existing suites pass. (Pre-existing SearchPage / ResourcePage / SignInPage failures reproduce on main — an unrelated localStorage env issue.)
• npm run build:bots — succeeds; scribe-fill and voice-transcribe are bundled into data/example/example-bots.json.
• App + bots typecheck clean (only the pre-existing UploadDataPage.tsx errors remain on main); lint clean.

Manual testing

Prerequisites

• An active PhenoML subscription. Set the Medplum Project secrets PHENOML_CLIENT_ID and PHENOML_CLIENT_SECRET (and PHENOML_BASE_URL if your env isn't the default experiment.app.pheno.ml). Project secrets are shared by all bots, so scribe-fill and voice-transcribe both pick them up.
• Custom profiles require a PhenoML develop or launch tier. Without it, scribe-fill transparently falls back to the generic questionnaireresponse profile (still steered by the inlined question key).

Setup

1. npm run dev (runs build:bots then Vite). If the dev server was already running from before this branch, restart it so the regenerated bot bundle includes the latest scribe-fill and voice-transcribe.
2. Upload Data → Deploy Bots — creates/deploys all bots, including scribe-fill and voice-transcribe. (Confirm via a Bot?name=voice-transcribe search if needed.)
3. Get Started → Import Screening Questionnaires — seeds GAD-7 and PHQ-9.

Run the flow
4. Open (or create) an encounter → Note & Tasks tab → Screening scribe section.
5. Provide a transcript one of two ways:

• Dictate: click the mic on the transcript box (or the chart note) and speak; on stop, the audio is posted to voice-transcribe → PhenoML /transcribe → the text appears in the box.
• Paste: copy from sample-visit-transcript.txt — Option A (live clinician/patient dialogue) or Option B (single-speaker post-visit dictation).

6. Click Generate screening questionnaires → GAD-7 and PHQ-9 render pre-filled with scored answers; each card shows a Score badge (sum of ordinalValues).
7. Edit any answer, then click Save to encounter on each card → a QuestionnaireResponse (status: completed, encounter set, subject = patient) is persisted.
8. Verify persistence — e.g. search QuestionnaireResponse?encounter=Encounter/<id> or view the encounter/patient. You can also confirm the generated profile was cached: StructureDefinition?url=https://www.medplum.com/fhir/StructureDefinition/qr-*.

Expected: with either sample transcript (both cover every item), GAD-7 scores high and PHQ-9 scores moderately high but not maxed (its psychomotor and self-harm items are "not at all"). Questions the transcript doesn't mention are left blank for the clinician to fill.

🤖 Generated with Claude Code

Prompt

Work only on Phase 2 of a six-phase refresh of this repo
(medplum-provider-lang2fhir), on a dedicated branch. Do not build
Phases 3 to 6, but do not make choices that block them.

Phase 1 (referral intake: fax/upload PDF to FHIR via referral-intake.ts,
review, then persist at sign-off) is complete and merged to main. Study
it and match its conventions.

Before writing any code, read these and summarize back to me: the bot
auth pattern and secret names, the scribe/transcription mechanism, and
how bots are registered and invoked. Then propose a plan and wait for my
confirmation.

• src/bots/referral-intake.ts
• src/bots/lang2fhir-create.ts
• src/scripts/deploy-bots.ts
• src/components/encounter/EncounterChart.tsx
• src/pages/resource/ResourceLang2FHIRCreatePage.tsx

Phase 2 goal: during a visit, a transcript auto-fills a screening
questionnaire for clinician review and save.

• Seed GAD-7 and PHQ-9 as FHIR Questionnaire resources (net-new seed
  JSON, loaded like existing seed data).
• Transcript capture: reuse the existing browser Whisper scribe from
  ResourceLang2FHIRCreatePage.tsx (@huggingface/transformers,
  whisper-tiny). Also accept pasted transcript text so the flow works
  without a microphone. Do not depend on any hosted transcribe API; none
  exists in this repo.
• Bot: reuse lang2fhir-create with resourceType QuestionnaireResponse,
  passing the target Questionnaire context plus the transcript. Add a
  thin scribe-fill wrapper only if extra prompt shaping is needed. Use
  the SDK auth pattern and the PHENOML_CLIENT_ID / PHENOML_CLIENT_SECRET
  / optional PHENOML_BASE_URL secrets that the existing bots use. Do not
  use PHENOML_EMAIL/PASSWORD.
• UI: add a Scribe action in EncounterChart.tsx (it uses a tab/activeTab
  structure). Run the bot, render the returned QuestionnaireResponse in
  an editable form (Medplum's QuestionnaireForm or the existing
  TaskQuestionnaireForm) for review and edit, then save linked to the
  encounter. Mirror the Phase 1 review-before-persist pattern.
• Register any new bot in deploy-bots.ts.

Constraints:

• Keep all existing tests passing and add tests for new code in the
  repo's existing style.
• Do not change Phase 1 behavior.
• Build shared pieces (questionnaire seeding, scribe capture, bot
  invocation helper) so Phases 3 to 6 can reuse them.

Acceptance: paste or speak a psychiatry visit note, GAD-7 and PHQ-9
pre-fill with scored answers, the clinician can edit, and saving
persists a QuestionnaireResponse linked to the encounter.

Branch name: phase-2-visit-scribe. Open a PR with a short description.

[kerbearasaurus]

do we need this? it's a lot of post-processing that in practice I dont think we need

[goelalex]

Removed!