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.
¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..