Overview
While Sully.ai can generate clinical notes from transcripts alone, providing additional context significantly improves note accuracy and completeness. Context enrichment helps Sully:
- Personalize notes with correct patient demographics and pronouns
- Reference current medications in assessments and identify potential interactions
- Maintain continuity of care by understanding previous visits
- Follow your preferences for note structure and emphasis
- Incorporate external data like lab results or specialist recommendations
This guide covers all available context fields and best practices for using them effectively.
Available Context Fields
When creating notes, you can provide the following optional context fields:
| Field | Type | Description |
|---|
date | string | Visit date (ISO format or natural language) |
patientInfo | object | Patient demographics (name, DOB, gender) |
medicationList | string[] | Current medications the patient is taking |
previousNote | string | Previous visit note for continuity of care |
instructions | string | Specific instructions for note generation |
context | string | Any additional free-form context |
All fields are optional. Provide what you have available to improve note quality.
Patient Info
The patientInfo object provides basic patient demographics that appear in the note header and inform pronoun usage throughout the document.
Structure
{
"patientInfo": {
"name": "Jane Doe",
"dateOfBirth": "1985-03-22",
"gender": "female"
}
}
| Field | Type | Description |
|---|
name | string | Patient’s full name |
dateOfBirth | string | Date of birth (ISO format or natural language) |
gender | string | Patient’s gender (used for pronouns) |
How It’s Used
- Note header: Patient name and age derived from DOB appear at the top of the note
- Pronoun consistency: Gender informs pronoun usage (she/her, he/him, they/them)
- Age-appropriate language: Pediatric vs. adult clinical terminology
Code Example
import Sully from '@sullyai/sullyai';
const sully = new Sully();
const note = await sully.notes.create({
transcript: "Doctor: Good morning, what brings you in today?...",
noteType: { type: 'soap' },
patientInfo: {
name: 'Jane Doe',
dateOfBirth: '1985-03-22',
gender: 'female',
},
});
Medication List
The medicationList field accepts an array of medication strings representing the patient’s current medications.
Provide medications as strings. Include dosage information when available:
{
"medicationList": [
"Lisinopril 10mg daily",
"Metformin 500mg twice daily",
"Atorvastatin 40mg at bedtime",
"Aspirin 81mg daily"
]
}
How It’s Used
- Medication reconciliation: Referenced in the Subjective or History section
- Assessment context: Helps identify drug interactions or contraindications
- Plan decisions: Informs medication adjustments or additions
- Allergy considerations: Cross-referenced when new medications are discussed
Code Example
import Sully from '@sullyai/sullyai';
const sully = new Sully();
const note = await sully.notes.create({
transcript: "Doctor: How are you feeling on your blood pressure medication?...",
noteType: { type: 'soap' },
medicationList: [
'Lisinopril 10mg daily',
'Metformin 500mg twice daily',
'Atorvastatin 40mg at bedtime',
'Aspirin 81mg daily',
],
});
Include dosage and frequency when available. “Metformin 500mg twice daily” provides more useful context than just “Metformin”.
Previous Notes
The previousNote field accepts the text of a previous visit note. This is particularly powerful for follow-up visits where continuity of care is important.
How It’s Used
- Continuity of care: References previous diagnoses, treatments, and recommendations
- Progress tracking: Notes improvement or worsening of conditions
- Follow-up references: “Patient returns for follow-up of…” language
- Treatment response: Documents how the patient responded to previous interventions
Best Use Cases
| Visit Type | Previous Note Value |
|---|
| Follow-up visit | Previous visit note for same condition |
| Post-procedure | Pre-procedure or procedure note |
| Chronic disease management | Most recent note for that condition |
| Hospital discharge follow-up | Discharge summary |
Code Example
import Sully from '@sullyai/sullyai';
const sully = new Sully();
const previousNote = `
SUBJECTIVE: 45-year-old female presenting with migraine headaches occurring 3-4 times per week.
Reports throbbing pain, photophobia, and nausea. Current medications ineffective.
ASSESSMENT: Chronic migraine without aura, poorly controlled.
PLAN:
1. Start sumatriptan 50mg PRN for acute episodes
2. Begin topiramate 25mg daily for prophylaxis
3. Headache diary for 4 weeks
4. Return in 4 weeks to assess response
`;
const note = await sully.notes.create({
transcript: "Doctor: Welcome back. How have the new medications been working for your migraines?...",
noteType: { type: 'soap' },
previousNote: previousNote,
});
For follow-up visits, providing the previous note is one of the most impactful context enrichments you can make. It enables Sully to generate notes that reflect the ongoing patient journey rather than treating each visit in isolation.
Custom Instructions
The instructions field accepts free-text instructions that guide how the note should be generated. Use this for specialty-specific requirements or personal preferences.
Example Instructions
| Use Case | Example Instruction |
|---|
| Specialty focus | ”Focus on cardiovascular symptoms and risk factors” |
| Format preference | ”Use bullet points for the assessment section” |
| Detail level | ”Keep the plan section brief with only essential items” |
| Compliance | ”Include ICD-10 codes for all diagnoses” |
| Style | ”Write in third person, past tense” |
How It’s Used
- Section emphasis: Guides which sections receive more detail
- Formatting preferences: Influences use of lists, paragraphs, headers
- Content inclusion: Ensures specific elements are captured
- Tone adjustment: Modifies clinical vs. patient-friendly language
Code Example
import Sully from '@sullyai/sullyai';
const sully = new Sully();
const note = await sully.notes.create({
transcript: "Doctor: Tell me about your chest discomfort...",
noteType: { type: 'soap' },
instructions: 'Focus on cardiovascular symptoms. Include differential diagnosis in assessment. Use numbered list for plan items.',
});
Instructions work best when they are specific and actionable. “Be thorough” is less effective than “Include all mentioned symptoms with onset, duration, and severity.”
Free-form Context
The context field accepts any additional information that doesn’t fit into the other structured fields. This is your catch-all for relevant clinical data.
Common Use Cases
- Lab results: Recent bloodwork, imaging findings
- Specialist recommendations: Notes from referrals
- Patient preferences: Treatment preferences, concerns
- Social context: Relevant life events, support system
- Historical data: Past surgical history, family history
Code Example
import Sully from '@sullyai/sullyai';
const sully = new Sully();
const note = await sully.notes.create({
transcript: "Doctor: I've reviewed your recent lab work. Let's discuss the results...",
noteType: { type: 'soap' },
context: `
Recent Labs (2024-01-10):
- HbA1c: 7.8% (up from 7.2% three months ago)
- Fasting glucose: 156 mg/dL
- Creatinine: 1.1 mg/dL (stable)
- eGFR: 72 mL/min
Cardiology consult note (2024-01-05):
Recommend continuing current cardiac medications.
Echo shows preserved EF at 55%.
No intervention needed at this time.
Patient expressed concern about adding more medications due to cost.
`,
});
Complete Example
Here’s a full API call using all available context fields:
import Sully from '@sullyai/sullyai';
const sully = new Sully();
const note = await sully.notes.create({
// Required: the transcript
transcript: `
Doctor: Good afternoon, Mrs. Johnson. How have you been since our last visit?
Patient: The headaches are much better since starting the new medication. I'm only getting them once a week now instead of every day.
Doctor: That's excellent progress. Any side effects from the topiramate?
Patient: A little tingling in my fingers sometimes, but nothing too bothersome.
Doctor: That's a common side effect and usually improves over time. Let's continue the current regimen.
`,
noteType: { type: 'soap' },
// Visit date
date: '2024-01-15',
// Patient demographics
patientInfo: {
name: 'Sarah Johnson',
dateOfBirth: '1979-06-14',
gender: 'female',
},
// Current medications
medicationList: [
'Topiramate 50mg daily',
'Sumatriptan 50mg PRN',
'Ibuprofen 400mg PRN',
],
// Previous visit note for continuity
previousNote: `
Date: 2023-12-15
SUBJECTIVE: 44-year-old female with chronic migraines, occurring daily for past 2 months.
ASSESSMENT: Chronic migraine without aura, poorly controlled on current regimen.
PLAN: Start topiramate 25mg daily, titrate to 50mg after 1 week. Continue sumatriptan PRN.
Return in 4 weeks.
`,
// Custom instructions
instructions: 'Document the improvement in migraine frequency. Note the paresthesia side effect and that it is being tolerated.',
// Additional context
context: `
Patient works as an accountant. Busy season approaching (tax season) -
she expressed concern about maintaining productivity.
Prefers to avoid additional medications if possible.
`,
});
console.log('Note ID:', note.data.noteId);
Best Practices
Provide Context When Available
Every piece of context you provide improves note quality. Even partial information helps:
| What You Have | What to Provide |
|---|
| Patient name only | patientInfo: { name: "..." } |
| Some medications | Provide what you know |
| Partial previous note | Better than nothing |
Avoid Unnecessary PHI
Only include PHI that should appear in the generated note:
- Include: Patient name (if needed in header), relevant medical history
- Avoid: Social Security numbers, full addresses, insurance details
Use Instructions for Specialty Needs
Different specialties have different documentation requirements:
| Specialty | Example Instructions |
|---|
| Cardiology | ”Include cardiovascular risk factor assessment” |
| Psychiatry | ”Document mental status exam findings in detail” |
| Pediatrics | ”Include developmental milestones and growth percentiles” |
| Surgery | ”Focus on surgical indications and planned procedure” |
Leverage Previous Notes for Follow-ups
For follow-up visits, previousNote provides the most value:
- Enables “Patient returns for follow-up of…” language
- Allows comparison of symptoms over time
- Documents treatment response
- Maintains diagnostic continuity
If your EHR can programmatically retrieve the previous note for a patient, automate including it in your API calls. This single enrichment dramatically improves follow-up note quality.
Next Steps