Ambient Session

​

Create a Session

do {
    let sessionContext: [String: Any] = [
        SukiAmbientConstant.kPatientInfo: [
            SukiAmbientConstant.kName: "Saran Goda",
            SukiAmbientConstant.kBirthdate: Date(), // yyyy-mm-dd format
            SukiAmbientConstant.kGender: "MALE"
        ],
        SukiAmbientConstant.kSections: [
            ["title": "History", "description": "History"],
            ["title": "Review of systems", "description": "Review of systems"]
        ],
        SukiAmbientConstant.kSessionId: UUID().uuidString.lowercased(),
        SukiAmbientConstant.kMultilingual: true
    ]
    sessionId = try SukiAmbientCore.shared.createSession(withSessionInfo: sessionContext, onCompletion: { _ in })
} catch {
    print(error)
}

• Include patient name, birthdate, and gender.
• Specify sections for which you want content generated (defaults are provided if omitted).
• Optionally, provide a session ID or let the SDK generate one.
• You can pass the multilingual parameter (Boolean) to indicate whether the session should be processed in multilingual mode:
  • true: Enables multilingual processing for this session.
  • false: Defaults to English.
  • This setting applies per session and does not change mid-session.
• Handle errors using SukiAmbientCoreError.

​

Set Session Context (Optional but Recommended)

public func setSessionContext(
    with context: ContextDetail,
    onCompletion completionHandler: SessionContextCallback
)

do {
    let contextDetail: [String: AnyHashable] = [
        SukiAmbientConstant.kPatientInfo: [
            SukiAmbientConstant.kBirthdate: Date(), // yyyy-mm-dd format
            SukiAmbientConstant.kGender: "MALE"
        ],
        SukiAmbientConstant.kProviderContext: [
            SukiAmbientConstant.kSpeciality: "FAMILY_MEDICINE"
        ],
        SukiAmbientConstant.kSections: [
            [
                SukiAmbientConstant.kCode: "51848-0",
                SukiAmbientConstant.kCodeType: "loinc"
            ],
            [
                SukiAmbientConstant.kCode: "11450-4", 
                SukiAmbientConstant.kCodeType: "loinc"
            ]
        ],
        SukiAmbientConstant.kDiagnosisInfo: [
            [
                SukiAmbientConstant.kDiagnosisNote: "Patient presents with chest pain",
                SukiAmbientConstant.kCodes: [
                    [
                        SukiAmbientConstant.kCodeType: "ICD-10",
                        SukiAmbientConstant.kCode: "R06.02",
                        SukiAmbientConstant.kCodeDescription: "Shortness of breath"
                    ]
                ]
            ]
        ]
    ]
    
    try SukiAmbientCore.shared.setSessionContext(with: contextDetail) { result in
        // Handle completion result
    }
} catch {
    print(error)
}

• context: A dictionary of type [String: AnyHashable] that may contain the following keys:
  • SukiAmbientConstant.kPatientInfo: Dictionary containing:
    • SukiAmbientConstant.kBirthdate: Date
    • SukiAmbientConstant.kGender: String
  • SukiAmbientConstant.kProviderContext: Dictionary containing:
    • SukiAmbientConstant.kSpeciality: String
  • SukiAmbientConstant.kSections: Array of dictionaries: Each with SukiAmbientConstant.kCode and SukiAmbientConstant.kCodeType (e.g., “loinc”)

• SukiAmbientConstant.kDiagnosisInfo: An Array of Dictionaries used to pass structured diagnosis context for the session.
  • Each dictionary may include:
    • SukiAmbientConstant.kDiagnosisNote: String (Optional note related to the diagnosis)
    • SukiAmbientConstant.kCodes: [Dictionary] (Array of dictionaries) — must contain at least one valid diagnosis code.
      • Each dictionary may include:
        • SukiAmbientConstant.kCodeType: String (e.g., “ICD-10”, “IMO”, “SNOMED”) (Required)
        • SukiAmbientConstant.kCode: String (Required)
        • SukiAmbientConstant.kCodeDescription: String (Optional)

• Can only be called after a session is successfully created.
• Pass only valid Specialities and LOINC codes.
• The session context dictionary should contain patient information such as birthdate (in yyyy-mm-dd format) and gender.
• diagnosisNote is optional.
• Each code entry must include codeType and code.
• codeDescription is optional but recommended for clarity.
• Sections are no longer required, LOINC codes alone are sufficient, and the SDK will automatically generate the appropriate clinical sections based on the provided codes.
• The setSessionContext function now internally uses a PATCH API that supports partial updates.

​

Recording Controls

do {
    try SukiAmbientCore.shared.start()
} catch {
    print(error)
}

do {
    try SukiAmbientCore.shared.pause()
} catch {
    print(error)
}

do {
    try SukiAmbientCore.shared.resume()
} catch {
    print(error)
}

do {
    try SukiAmbientCore.shared.end()
} catch {
    print(error)
}

do {
    try SukiAmbientCore.shared.cancel()
} catch {
    print(error)
}

• Always ensure the SDK is initialized and a session is created before calling these methods.
• Handle all errors using SukiAmbientCoreError.
• iOS does not allow starting a recording in the background; handle appIsNotActive errors with user notifications if needed.

​

Session Status & Content Retrieval

​

Get Suggestion Generation Status

SukiAmbientCore.shared.status(for: recordingId) { result in
    switch result {
    case .success(let status):
        print("status \(status)")
    case .failure(let error):
        print("error \(error)")
    }
}

​

Get Generated Suggestions

SukiAmbientCore.shared.content(for: recordingId) { result in
    switch result {
    case .success(let suggestions):
        print("suggestions \(suggestions)")
    case .failure(let error):
        print("error \(error)")
    }
}

​

Get Audio Transcript

SukiAmbientCoreManager.shared.transcript(for: recordingId) { result in
    switch result {
    case .success(let response):
        let transcriptText = (response.finalTranscript ?? []).compactMap { $0.transcript }.joined()
        print(transcriptText)
    case .failure(let error):
        print(error)
    }
}

​

Get Structured Data

SukiAmbientCore.shared.getStructuredData(for: recordingId) { result in
    switch result {
    case .success(let structuredData):
        print("Structured Data: \(structuredData)")
    case .failure(let error):
        print("error \(error)")
    }
}

​

Submit User Feedback

​

Function Signature

public func submitFeedback(
    _ submission: FeedbackSubmission,
    for recordingId: RecordingId,
    onCompletion completionHandler: @escaping ((Result<String, Error>) -> Void)
)
public typealias RecordingId = String

​

Required Data Structures

public struct FeedbackSubmission {
    public let entity: FeedbackEntity
    public let quantitative: QuantitativeFeedback
    public let comments: String?
    
    public init(entity: FeedbackEntity,
                quantitative: QuantitativeFeedback,
                comments: String? = nil)
}

public enum FeedbackEntity: String {
    case content = "content"
}

public struct QuantitativeFeedback {
    public let minRating: Int
    public let maxRating: Int
    public let rating: Int
    
    public init(minRating: Int, maxRating: Int, rating: Int)
}

​

Implementation Example

// 1. Create the quantitative feedback object.
let quantitativeFeedback = QuantitativeFeedback(minRating: 1, maxRating: 5, rating: 4)

// 2. Create the full feedback submission object.
let submission = FeedbackSubmission(
    entity: .content,
    quantitative: quantitativeFeedback,
    comments: "The patient's history was captured accurately."
)

// 3. Call the submit method with the submission object and recording ID.
SukiAmbientCoreManager.shared.submitFeedback(submission, for: recordingId) { result in
    switch result {
    case .success(let feedbackId):
        print("Feedback submitted successfully with ID: \(feedbackId)")
    case .failure(let error):
        print("Error submitting feedback: \(error)")
    }
}

​

Rating System

• The maxRating must be greater than the minRating.
• The rating must be within the inclusive range of minRating and maxRating.
• The comments string is optional and has a maximum length of 2000 characters.

​

Key Points to Note:

• This code asynchronously fetches the content of the generated suggestions for the specified recording ID.
• The completion block contains either the generated suggestions or an error in case there’s an issue while fetching the content.
• Ensure that the SDK is initialized and the recording ID is valid before calling this method.
• All methods are asynchronous and require a valid recording ID.
• The completion block returns either the result or an error.

​

Clearing Sessions

do {
    try SukiAmbientCore.shared.clear()
} catch {
    print(error)
}

• Use during user logout to clear all sessions.
• Do not call during an active session; this will throw an error.

​

Session Events & Delegates

extension AppDelegate: SukiAmbientSessionDelegate {
    func sukiAmbient(sessionEvent event: SukiAmbientCore.SessionEvent, for recordingId: SukiAmbientCore.RecordingId) {
        // Handle session events here
    }
}

​

Session Events enum:

public enum SessionEvent {
    case started
    case resumed
    case paused
    case ended
    case cancelled
    case suggestionGenerationInProgress
    case suggestionsGenerated
    case suggestionsGenerationFailed
    case audioInterruptionStarted
    case audioInterruptionEnded
    case convertedToOfflineSession
    case pendingOfflineUpload
    case preparingOfflineUpload
    case uploadingAudio
    case audioUploadFailed
    case audioUploadAllRetryFailed
    case audioUploaded
    case processingUpload
    case processingUploadFailed
}

​

Best Practices

• Always check SDK initialization and session state before calling methods.
• Handle all errors and provide user feedback, especially for background/foreground transitions.
• Use local notifications for important background errors.
• Store the unique session/recording ID for future operations.

​

Offline Mode

• Continue recording audio locally on the device
• Store the audio and metadata securely on the device
• Automatically attempt to upload the stored data once the connection is restored
• Queue session events and sync them when connectivity returns

• Network interruptions or poor cellular/WiFi connectivity
• Temporary backend unavailability
• WebSocket connection drops during audio streaming
• Token-related authentication failures
• Device switching between networks (WiFi to cellular)

​

Important Notes:

• The SDK automatically manages offline/online transitions without manual intervention
• Audio quality and session integrity are maintained during offline periods
• Multiple offline sessions can be queued and uploaded when connectivity returns
• Local storage is encrypted and secure
• Battery optimization is considered during offline recording

​

Best Practices & Error Handling

• Always ensure the SDK is initialized and a session is created before calling recording methods.
• Handle SukiAmbientCoreError in all operations to provide robust error feedback.
• For background recording, be aware of iOS limitations: recording cannot be started in the background, and background execution time is limited.
• Use local notifications to inform users if errors occur while the app is backgrounded.
• Store the unique recording/session ID for future operations such as status changes or retrieving content.