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
| Name | Type | Required | Description |
|---|---|---|---|
transcript | text | Yes | Clinical encounter transcript (min 10 characters) |
additional_context | text | No | Optional context for generation (specialty, patient age, visit type) |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
soap_note | json | No | Structured note parsed from the model output, with metadata stamped (generated_at, model_used, transcript_length) |
model_used | text | No | Model name reported in the note metadata |
success | boolean | No | Whether generation succeeded |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| System Prompt | system_prompt | text | Yes | Clinical documentation prompt — deployment-supplied, never built in (canonical docline prompt: docs/examples/medical-notes/soap_system_prompt.txt) | ||
| Output JSON Schema | output_schema | json | No | Strict structured-output schema for the note; empty disables response_format (canonical: docs/examples/medical-notes/soap_output_schema.json) | ||
| Model | model | string | No | gpt-4o | Model name (must support strict json_schema structured output when output_schema is set) |
Auth
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| API Key | api_key | secret | Yes | API key for the OpenAI-compatible provider |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Schema Name | schema_name | string | No | soap_note | Name sent with the json_schema response format | |
| Base URL | base_url | string | No | OpenAI-compatible endpoint override (gateways, testing) | ||
| Temperature | temperature | number | No | 0 | min 0; max 1 | Sampling temperature; keep at 0 for deterministic clinical output |
| Max Tokens | max_tokens | number | No | 4000 | min 256; max 16000 | Maximum tokens for the generated note |
| Display Model Name | display_model_name | string | No | Overrides the model name reported in note metadata (empty = real model) |
Errors
| Code | Description |
|---|---|
API_KEY_REQUIRED | No API key configured for the LLM provider |
PROMPT_REQUIRED | system_prompt config is missing or empty |
INVALID_SCHEMA | output_schema is not a valid JSON object |
TRANSCRIPT_TOO_SHORT | Transcript missing or shorter than 10 characters |
LLM_REQUEST_FAILED | The LLM API call failed |
INVALID_JSON | The model returned output that is not valid JSON |
EMPTY_RESPONSE | The 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.
Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.