Clinical-note structurer

What this template is

Pattern: extractor that converts free-text clinician dictation into EHR-schema structured fields. Closed-enum ICD-10 chapter + medication-class lists bound the output; numeric confidence per field. Reviewer-gate on schema violation catches the cases where the LLM produces ICD codes outside the closed enum. Reject-on-failure (rather than fallback default) — better to surface an error than to write a wrong code into the EHR.

import { RuntimeAISpec } from '@promethean/runtime-ai';

export const clinicalNoteStructurerSpec: RuntimeAISpec = {
  specId: 'clinical-note-structurer-v1',
  displayName: 'Clinical-note structurer',
  description:
    'Free-text clinical note → ICD-10 + medication + problem-list extraction.',
  category: 'extractor',
  schemaVersion: 'promethean-runtime-ai-spec-1.0',
  canonicalForm: 'v1',

  inputSchema: {
    fields: [
      { name: 'encounterId', type: 'string', required: true,
        redaction: 'hash-only' },
      // PHI: hashed only. Operator retains the raw note under its
      // own HIPAA-compliant data store.
      { name: 'noteText', type: 'string', required: true,
        maxLength: 8000, redaction: 'hash-only' },
      { name: 'specialty', type: 'enum', required: true,
        enumValues: [
          'primary-care', 'cardiology', 'oncology',
          'mental-health', 'pediatrics', 'other',
        ] },
    ],
  },

  outputSchema: {
    fields: [
      { name: 'icdCodes', type: 'string-list', required: false,
        maxItems: 12, maxLength: 8 },
      { name: 'medicationsRxNorm', type: 'string-list', required: false,
        maxItems: 12, maxLength: 64 },
      { name: 'problemListItems', type: 'string-list', required: false,
        maxItems: 10, maxLength: 120 },
      { name: 'confidence', type: 'number', required: true,
        min: 0, max: 1 },
      { name: 'hallucinationFlagged', type: 'boolean', required: true },
    ],
  },

  promptTemplate: {
    system:
      'Extract ICD-10 codes, RxNorm medication identifiers, ' +
      'and problem-list items from the clinical note. ' +
      'ICD-10 codes must be real codes. ' +
      'If uncertain, set hallucinationFlagged=true and confidence < 0.5.',
    user:
      'Encounter {{encounterId}} ({{specialty}}). ' +
      'Note: {{noteText}}.',
  },

  modelIdentity: {
    provider: 'anthropic',
    model: 'claude-sonnet-4-5',
    version: '20250929',
  },

  reviewerGate: 'on-schema-violation',
  maxLatencyMs: 3000,
  fallbackBehavior: 'reject',
};

Regulations addressed

This template's configuration choices map to specific regulatory obligations. The substrate doesn't certify compliance — but the spec hash + reviewer-verdict + modelIdentity per L12 entry give you the evidence layer for these citations:

• ·MDR Annex VIII rule 11 — Class IIa software
• ·HIPAA §164.312(b) — audit controls
• ·AI Act Art. 6(1) — high-risk via MDR

See citations index for official source URLs →