Zum Hauptinhalt springen

SOAP Note Generator

Category: AI & ML
Node id: soap-generate
Maturity: production
Risk tier: B

Standards: HIPAA

Generates a structured SOAP note (Subjective, Objective, Assessment, Plan) from a clinical encounter transcript via a single deterministic LLM call; the clinical prompt and output JSON schema are supplied in configuration

What it does​

  • Strict json_schema structured output (OpenAI response_format)
  • Deployment-supplied clinical prompt and schema — no clinical content compiled into the binary
  • Deterministic runtime metadata stamping (generated_at, model_used, transcript_length)
  • Same-language output when the configured prompt demands it

Use cases​

  • Generate a draft SOAP note from a Docline telemedicine encounter transcript
  • Convert speech-to-text output of a clinical visit into structured documentation
  • Produce reviewable clinical drafts that a clinician signs in the consuming application

Runtime​

  • Performance tier: slow

Input ports​

NameTypeRequiredDescription
transcripttextYesClinical encounter transcript (min 10 characters)
additional_contexttextNoOptional context for generation (specialty, patient age, visit type)

Output ports​

NameTypeRequiredDescription
soap_notejsonNoStructured note parsed from the model output, with metadata stamped (generated_at, model_used, transcript_length)
model_usedtextNoModel name reported in the note metadata
successbooleanNoWhether generation succeeded

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
System Promptsystem_prompttextYesClinical documentation prompt — deployment-supplied, never built in (canonical docline prompt: docs/examples/medical-notes/soap_system_prompt.txt)
Output JSON Schemaoutput_schemajsonNoStrict structured-output schema for the note; empty disables response_format (canonical: docs/examples/medical-notes/soap_output_schema.json)
ModelmodelstringNogpt-4oModel name (must support strict json_schema structured output when output_schema is set)

Auth​

SettingNameTypeRequiredDefaultAllowed valuesDescription
API Keyapi_keysecretYesAPI key for the OpenAI-compatible provider

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Schema Nameschema_namestringNosoap_noteName sent with the json_schema response format
Base URLbase_urlstringNoOpenAI-compatible endpoint override (gateways, testing)
TemperaturetemperaturenumberNo0min 0; max 1Sampling temperature; keep at 0 for deterministic clinical output
Max Tokensmax_tokensnumberNo4000min 256; max 16000Maximum tokens for the generated note
Display Model Namedisplay_model_namestringNoOverrides the model name reported in note metadata (empty = real model)

Errors​

CodeDescription
API_KEY_REQUIREDNo API key configured for the LLM provider
PROMPT_REQUIREDsystem_prompt config is missing or empty
INVALID_SCHEMAoutput_schema is not a valid JSON object
TRANSCRIPT_TOO_SHORTTranscript missing or shorter than 10 characters
LLM_REQUEST_FAILEDThe LLM API call failed
INVALID_JSONThe model returned output that is not valid JSON
EMPTY_RESPONSEThe model returned an empty response

Runtime notes​

  • The note is a DRAFT for clinician review — this node never writes to an EHR or acts on its output
  • system_prompt and output_schema carry the clinical content; the node itself ships none (MDR artefact posture, clinical-release-markers rule 2)
  • soap_note.metadata is stamped post-generation with generated_at (naive-UTC microseconds, legacy format), model_used and transcript_length
  • The transcript is sent to the configured LLM provider — a deliberate PHI egress (HYDRA-SOAP-TDD-001 §6)
  • Hard failures (API error, invalid JSON) return a node error; the node never emits a partial note

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..