Note Generation¶

The NoteManager class handles all operations related to generating medical notes from audio recordings.

Note Manager Class¶

notedx_sdk.core.note_manager.NoteManager ¶

NoteManager(client: NoteDxClient)

Manages medical note generation from audio files using the NoteDx API.

This class provides a high-level interface for:

Converting audio recordings to medical notes
Managing note generation jobs
Retrieving generated notes and transcripts
Monitoring system status

The NoteManager handles all API authentication and error handling, making it easy to integrate medical note generation into your application.

Example

>>> from notedx_sdk import NoteDxClient
>>> client = NoteDxClient(api_key="your-api-key")
>>> note_manager = client.notes
>>> 
>>> # Generate a medical note from an audio file
>>> response = note_manager.process_audio(
...     file_path="patient_visit.mp3",
...     visit_type="initialEncounter",
...     recording_type="dictation",
...     template="primaryCare"
... )
>>> job_id = response["job_id"]
>>> 
>>> # Check status and get the note when ready
>>> status = note_manager.fetch_status(job_id)
>>> if status["status"] == "completed":
...     note = note_manager.fetch_note(job_id)
...     print(note["note"])

Initialize the NoteManager.

PARAMETER	DESCRIPTION
`client`	The NoteDxClient instance. TYPE: `NoteDxClient`

Functions¶

set_logger ¶

set_logger(
    level: Union[int, str],
    handler: Optional[Handler] = None,
) -> None

Set the logger level and handler.

PARAMETER	DESCRIPTION
`level`	The logging level (e.g., logging.INFO). TYPE: `Union[int, str]`
`handler`	Optional logging handler. TYPE: `Optional[Handler]` DEFAULT: `None`

configure_logging `classmethod` ¶

configure_logging(
    level: Union[int, str] = logging.INFO,
    handler: Optional[Handler] = None,
) -> None

Configure logging for the SDK.

PARAMETER	DESCRIPTION
`level`	The logging level (e.g., logging.DEBUG, logging.INFO) TYPE: `Union[int, str]` DEFAULT: `INFO`
`handler`	Optional logging handler to add. If None, logs to console. TYPE: `Optional[Handler]` DEFAULT: `None`

Example

>>> # Enable debug logging to console
>>> NoteManager.configure_logging(logging.DEBUG)
>>> 
>>> # Log to a file
>>> file_handler = logging.FileHandler('notedx.log')
>>> NoteManager.configure_logging(logging.INFO, file_handler)

process_audio ¶

process_audio(
    file_path: str,
    visit_type: Optional[
        Literal["initialEncounter", "followUp"]
    ] = None,
    recording_type: Optional[
        Literal["dictation", "conversation"]
    ] = None,
    patient_consent: Optional[bool] = None,
    lang: Literal["en", "fr"] = "en",
    output_language: Optional[Literal["en", "fr"]] = None,
    template: Optional[
        Literal[
            "primaryCare",
            "er",
            "psychiatry",
            "surgicalSpecialties",
            "medicalSpecialties",
            "nursing",
            "radiology",
            "procedures",
            "letter",
            "pharmacy",
            "social",
            "wfw",
            "smartInsert",
        ]
    ] = None,
    documentation_style: Optional[
        Literal["soap", "problemBased"]
    ] = None,
    custom: Optional[Dict[str, Any]] = None,
    chunk_size: Optional[int] = None,
) -> Dict[str, Any]

Converts an audio recording into a medical note using the specified template.

POST /process-audio

This method handles the complete flow of audio processing and note generation:

Validates the audio file format and parameters
Securely uploads the file
Initiates the note generation process
Returns a job ID for tracking progress

PARAMETER	DESCRIPTION
`file_path`	Path to the audio file. Supported formats: `.mp3`, `.mp4`, `.m4a`, `.aac`, `.wav`, `.flac`, `.pcm`, `.ogg`, `.opus`, `.webm` TYPE: `str`
`visit_type`	Type of medical visit (optional). * `initialEncounter`: First visit with patient * `followUp`: Subsequent visit Required for standard templates, optional for 'wfw'/'smartInsert'. TYPE: `Optional[Literal['initialEncounter', 'followUp']]` DEFAULT: `None`
`recording_type`	Type of audio recording (optional). * `dictation`: Single speaker dictation * `conversation`: Multi-speaker conversation (requires patient_consent) Required for standard templates, optional for 'wfw'/'smartInsert'. TYPE: `Optional[Literal['dictation', 'conversation']]` DEFAULT: `None`
`patient_consent`	Whether patient consent was obtained (optional). Required for conversation mode, optional otherwise. TYPE: `Optional[bool]` DEFAULT: `None`
`lang`	Source language of the audio. Defaults to 'en'. * `en`: English * `fr`: French TYPE: `Literal['en', 'fr']` DEFAULT: `'en'`
`output_language`	Target language for the note (optional). If not specified, uses the same language as the source. TYPE: `Optional[Literal['en', 'fr']]` DEFAULT: `None`
`template`	Medical note template to use. The template determines how the audio content will be structured in the final note. TYPE: `Optional[Literal['primaryCare', 'er', 'psychiatry', 'surgicalSpecialties', 'medicalSpecialties', 'nursing', 'radiology', 'procedures', 'letter', 'pharmacy', 'social', 'wfw', 'smartInsert']]` DEFAULT: `None`
`documentation_style`	Style of the documentation (optional). `soap`: The classic SOAP note style `problemBased`: Problem based documentation style, where each problem is a section of the note TYPE: `Optional[Literal['soap', 'problemBased']]` DEFAULT: `None`

Note

If left empty, the default documentation style of the template is used, i.e. structured
Common sections are: Identification, Chief complaint, Past medical and surgical history, Past investigations, Medication and allergies, Lifestyle habits, Family history, Social history, HPI, Physical exam, Assessment, Plan.

Standard templates (require visit_type and recording_type):

primaryCare - Primary care visit for a general practitioner
er - Emergency room visit
psychiatry - Psychiatric evaluation
surgicalSpecialties - Surgical specialties (Any)
medicalSpecialties - Medical specialties (Any)
nursing - Nursing notes
pharmacy - Pharmacy notes
radiology - Radiology reports
procedures - Procedure notes (small procedures, biopsies, outpatient surgeries, etc.)
letter - Medical letter to the referring physician
social - Social worker notes

Special templates (only require file_path and lang):

wfw - Word for word transcription, supports inclusion of formatting and punctuation during dictation
smartInsert - Smart insertion mode

custom: Additional parameters for note generation (optional).
Dictionary that can contain:

* `context`: Additional patient context (history, demographics, medication, etc.)
* `template`: A complete custom template as a string (SOAP note, other etc...)

chunk_size: Size of upload chunks in bytes (optional).
Defaults to 1MB. Adjust for large files or slow connections.

RETURNS	DESCRIPTION
`dict`	A dictionary containing: `job_id`: Unique identifier for tracking the job `presigned_url`: URL for uploading the audio file `status`: Initial job status TYPE: `Dict[str, Any]`

RAISES	DESCRIPTION
`ValidationError`	If parameters are invalid or missing
`UploadError`	If file upload fails
`AuthenticationError`	If API key is invalid
`PaymentRequiredError`	If: Free trial jobs are depleted (100 jobs limit) Payment is required for subscription Account has exceeded usage limits
`AuthorizationError`	If API key lacks permissions
`InactiveAccountError`	If account is inactive or pending setup
`NetworkError`	If connection issues occur
`BadRequestError`	If API rejects the request
`InternalServerError`	If server error occurs

Examples:

Standard template usage:

response = note_manager.process_audio(
    file_path="visit.mp3",
    visit_type="initialEncounter",
    recording_type="dictation",
    template="primaryCare"
)
job_id = response["job_id"]

Word-for-word transcription:

response = note_manager.process_audio(
    file_path="dictation.mp3",
    lang="en",
    template="wfw"
)

Notes

The custom object provides powerful customization capabilities:

It accepts a dictionary with context and template keys (both must be strings)
The template value replaces the default note template

Example custom object:

custom = {
    "context": "Past medical history: ACL tear 10 years ago on the right knee.",
    "template": '''A new custom SOAP note template.

    IDENTIFICATION AND CHIEF COMPLAINT:
    - Include the patient's identification and chief complaint here.

    PAST MEDICAL HISTORY:
    - Include the patient's past medical history here and past investigations.

    SUBJECTIVE: 
    - Include the patient's subjective information here. Order by system. (Do not repeat the same information in the Identification and Chief complaint, Past medical history and Past investigations sections)

    OBJECTIVE: 
    - Include the patient's objective information here.

    ASSESSMENT: 
    - Include the patient's assessment here.

    PLAN: 
    - Include the patient's plan here.'''
}

You can create multiple custom templates and pass them in the custom object.
The custom object can be used in regenerate_note() to generate new notes from existing transcripts
The context key adds patient information not in the audio recording
smartInsert mode allows adding text snippets within a note (e.g., "Include a normal right knee exam")

Note

Each language need its own custom template if you want the note to be generated accurately.
For example, if you pass a custom template in english, but use lang and output_language as french, the note will be generated in french but the custom template but the sections might be in english.
Free trial users get 100 jobs before requiring payment
Job processing typically takes 20-30 seconds
Maximum file size is 500MB

regenerate_note ¶

regenerate_note(
    job_id: str,
    template: Optional[
        Literal[
            "primaryCare",
            "er",
            "psychiatry",
            "surgicalSpecialties",
            "medicalSpecialties",
            "nursing",
            "radiology",
            "procedures",
            "letter",
            "social",
            "wfw",
            "smartInsert",
        ]
    ] = None,
    output_language: Optional[Literal["en", "fr"]] = None,
    documentation_style: Optional[
        Literal["soap", "problemBased"]
    ] = None,
    custom: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]

Generates a new medical note from an existing transcript with different parameters.

POST /regenerate-note

This method allows you to:

Generate a new note using a different template
Translate the note to another language
Modify generation parameters without re-uploading audio

PARAMETER	DESCRIPTION
`job_id`	ID of the original job to regenerate from. Must be a completed job with a transcript. TYPE: `str`
`template`	New template to use for generation. See process_audio() for available templates. If not specified, uses the original template. TYPE: `str` DEFAULT: `None`
`output_language`	Target language for the new note: 'en': English 'fr': French If not specified, uses the original language. TYPE: `str` DEFAULT: `None`
`custom`	Additional parameters for note generation: context: Additional patient context (history, demographics, medication, etc.) template: A complete custom template as a string (SOAP note, other etc...) TYPE: `dict` DEFAULT: `None`
`documentation_style`	Style of the documentation (optional): 'soap': The classic SOAP note style 'problemBased': Problem based documentation style TYPE: `Optional[Literal['soap', 'problemBased']]` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict`	A dictionary containing: job_id (str): New job ID for the regenerated note status (str): Initial job status TYPE: `Dict[str, Any]`

RAISES	DESCRIPTION
`ValidationError`	If job_id is invalid
`JobNotFoundError`	If source job is not found
`JobError`	If source job has no transcript or had errors
`AuthenticationError`	If API key is invalid
`PaymentRequiredError`	If account payment is required
`NetworkError`	If connection issues occur

Example

>>> # First, get original job_id from process_audio
>>> response = note_manager.regenerate_note(
...     job_id="original-job-id",
...     template="er",  # Change template
...     output_language="fr"  # Translate to French
... )
>>> new_job_id = response["job_id"]
>>> # Use new_job_id to fetch regenerated note

fetch_status ¶

fetch_status(job_id: str) -> Dict[str, Any]

Gets the current status and progress of a note generation job.

GET /status/{job_id}

The job can be in one of these states:

'pending': Job created, waiting for file upload
'queued': File uploaded, waiting for processing
'transcribing': Audio file is being transcribed
'transcribed': Transcript ready, generating note
'completed': Note generation finished successfully
'error': Job failed with an error

PARAMETER	DESCRIPTION
`job_id`	The ID of the job to check. Obtained from process_audio() or regenerate_note(). TYPE: `str`

RETURNS	DESCRIPTION
`dict`	A dictionary containing: status (str): Current job status (see states above) message (str, optional): Status message or error details progress (dict, optional): Progress information TYPE: `Dict[str, Any]`

RAISES	DESCRIPTION
`JobNotFoundError`	If job_id is not found
`AuthenticationError`	If API key is invalid
`NetworkError`	If connection issues occur

Example

>>> status = note_manager.fetch_status("job-id")
>>> if status["status"] == "completed":
...     note = note_manager.fetch_note("job-id")
>>> elif status["status"] == "error":
...     print(f"Error: {status['message']}")

Note

Poll at least 5 seconds apart if you chose this method. Webhooks are HIGHLY recommended.
The full Job typically complete within 20-30 seconds.
Status history is preserved for 48 hours

fetch_note ¶

fetch_note(job_id: str) -> Dict[str, Any]

Retrieves the generated medical note for a completed job.

GET /fetch-note/{job_id}

The note includes:

Patient consent statement (if applicable)
Structured medical note based on template
Optional note title
Source/target language information

PARAMETER	DESCRIPTION
`job_id`	The ID of the job to fetch the note for. Job must be in 'completed' status. TYPE: `str`

RETURNS DESCRIPTION

dict

A dictionary containing:

note (str): The generated medical note text
note_title (str, optional): Title for the note
job_id (str): The job ID (for reference)
status (str): Job status (should be 'completed')
lang (str): Source language of the transcript
output_language (str): Target language for the note
recording_type (str): Type of recording (dictation/conversation)
visit_type (str): Type of visit (initialEncounter/followUp)
template (str): Template used for generation
is_sandbox (bool): Whether this is a sandbox job
timestamp (str): Job creation timestamp
ttl (int): Time-to-live in seconds for the job data

TYPE: Dict[str, Any]

RAISES	DESCRIPTION
`ValidationError`	If job_id is invalid
`JobNotFoundError`	If job or note is not found
`JobError`	If note generation is not completed
`AuthenticationError`	If API key is invalid
`NetworkError`	If connection issues occur

Example

>>> # First check status
>>> status = note_manager.fetch_status("job-id")
>>> if status["status"] == "completed":
...     result = note_manager.fetch_note("job-id")
...     print(f"Title: {result['note_title']}")
...     print(f"Note: {result['note']}")

Note

Always check job status before fetching note
Notes are available for 48 hours after completion
Notes include patient consent if provided
The note format follows the selected template

fetch_transcript ¶

fetch_transcript(job_id: str) -> Dict[str, Any]

Retrieves the raw transcript for a job after audio processing.

GET /fetch-transcript/{job_id}

The transcript represents the raw text from audio processing, before any medical note generation. Useful for:

Verifying audio processing accuracy
Debugging note generation issues
Keeping raw transcripts for records

PARAMETER	DESCRIPTION
`job_id`	The ID of the job to fetch the transcript for. Job must be in 'transcribed' or 'completed' status. TYPE: `str`

RETURNS	DESCRIPTION
`dict`	A dictionary containing: transcript (str): The raw transcript text job_id (str): The job ID (for reference) TYPE: `Dict[str, Any]`

RAISES	DESCRIPTION
`ValidationError`	If job_id is invalid
`JobNotFoundError`	If job or transcript is not found
`JobError`	If transcription is not completed
`AuthenticationError`	If API key is invalid
`NetworkError`	If connection issues occur

Example

>>> # Useful for verification
>>> transcript = note_manager.fetch_transcript("job-id")
>>> print(f"Raw text: {transcript['transcript']}")

Note

Available after transcription, before note generation
Preserved for 48 hours after job completion
Includes all recognized speech from audio
May contain speaker labels in conversation mode

get_system_status ¶

get_system_status() -> Dict[str, Any]

Retrieves system status and health information.

GET /system/status

Useful for:

Monitoring API availability
Checking processing latencies
Debugging connection issues

RETURNS	DESCRIPTION
`dict`	A dictionary containing: status (str): Overall system status services (dict): Status of individual services latency (dict): Current processing latencies TYPE: `Dict[str, Any]`

RAISES	DESCRIPTION
`AuthenticationError`	If API key is invalid
`NetworkError`	If connection issues occur
`ServiceUnavailableError`	If status check fails

Example

>>> status = note_manager.get_system_status()
>>> print(f"System status: {status['status']}")
>>> print(f"Average latency: {status['latency']['avg']}ms")

Note

Updated every minute
Includes all system components
Useful for monitoring and debugging
No authentication required

Templates¶

The SDK supports various medical note templates:

primaryCare: Primary care visit notes
er: Emergency room visit notes
psychiatry: Psychiatric evaluation notes
surgicalSpecialties: Surgical specialties notes
medicalSpecialties: Medical specialties notes
nursing: Nursing notes
radiology: Radiology reports
procedures: Procedure notes
letter: Medical letters
social: Social worker notes
wfw: Word-for-word transcription
smartInsert: Smart insertion mode

Usage Examples¶

Basic Note Generation¶

# Initialize client
client = NoteDxClient(api_key="your-api-key")

# Step 1: Process audio request - get job_id and upload URL
response = client.notes.process_audio(
    template="primaryCare",
    visit_type="initialEncounter",
    recording_type="dictation",
    lang="en"
)

# Get job ID and presigned URL
job_id = response["job_id"]
presigned_url = response["presigned_url"]

# Step 2: Upload the audio file using presigned URL
client.notes.upload_audio(
    presigned_url=presigned_url,
    file_path="visit_recording.mp3"
)

# Step 3: Check status until complete
while True:
    status = client.notes.fetch_status(job_id)
    if status["status"] == "completed":
        # Step 4: Get the note
        note = client.notes.fetch_note(job_id)
        print(note["note"])
        break
    elif status["status"] == "error":
        print(f"Error: {status['message']}")
        break
    time.sleep(5)  # Wait 5 seconds before checking again

Word-for-Word Transcription¶

# Get job_id and upload URL
response = client.notes.process_audio(
    template="wfw",
    lang="en"
)

# Upload the audio file
client.notes.upload_audio(
    presigned_url=response["presigned_url"],
    file_path="dictation.mp3"
)

Note Regeneration¶

# Regenerate with different template
new_response = client.notes.regenerate_note(
    job_id="original-job-id",
    template="er"
)

# Translate to French
translated = client.notes.regenerate_note(
    job_id="original-job-id",
    output_language="fr"
)

Error Handling¶

from notedx_sdk.exceptions import ValidationError, JobError

try:
    response = client.notes.process_audio(
        file_path="recording.mp3",
        template="invalid-template"
    )
except ValidationError as e:
    print(f"Invalid parameters: {e}")
except JobError as e:
    print(f"Job failed: {e}")

REST API Equivalent¶

# Step 1: Initialize processing and get upload URL
curl -X POST "https://api.notedx.io/v1/process-audio" \
     -H "x-api-key: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "template": "primaryCare",
       "visit_type": "initialEncounter",
       "recording_type": "dictation",
       "lang": "en"
     }'

# Response contains job_id and presigned_url

# Step 2: Upload audio file using presigned URL
curl -X PUT "${presigned_url}" \
     -H "Content-Type: audio/mpeg" \
     --data-binary "@recording.mp3"

# Step 3: Check processing status
curl "https://api.notedx.io/v1/status/{job_id}" \
     -H "x-api-key: your-api-key"

# Step 4: Get the generated note
curl "https://api.notedx.io/v1/fetch-note/{job_id}" \
     -H "x-api-key: your-api-key"

Note Generation¶

Note Manager Class¶

notedx_sdk.core.note_manager.NoteManager ¶

Functions¶

set_logger ¶

configure_logging classmethod ¶

process_audio ¶

regenerate_note ¶

fetch_status ¶

fetch_note ¶

fetch_transcript ¶

get_system_status ¶

Templates¶

Usage Examples¶

Basic Note Generation¶

Word-for-Word Transcription¶

Note Regeneration¶

Error Handling¶

REST API Equivalent¶

configure_logging `classmethod` ¶