Skip to main content

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.

Something unclear? Send documentation feedback by email.