Sofia Component

Sofia Component is an AI-powered medical assistant web component designed for healthcare applications. It provides intelligent medical transcription, report generation, and clinical decision support through a modern, framework-agnostic interface.

📖 Table of Contents

• Overview
• Installation
• Quick Start
• Examples
• Properties & Attributes
• Events
• Patient Data Structure
• Features
• Troubleshooting
• Additional Resources
• License

Overview

Sofia Component is part of the Sofia healthcare ecosystem. It works out of the box with any framework or vanilla JS, providing secure, real-time medical transcription and report generation.

Installation

npm install @omniloy/omniscribe-library
# or
yarn add @omniloy/omniscribe-library

Basic Usage

1. Import the component and its styles:

<script type="module">
  import 'omniscribe-library/dist/webcomponents.umd.js';
</script>

2. Use the component in your HTML:

<omniscribe-component
  baseurl="YOUR_API_BASE_URL"
  wssurl="YOUR_API_WSS_URL"
  apikey="YOUR_API_KEY"
  userid="USER_ID"
  patientid="PATIENT_ID"
  toolsargs="{}"
>
</omniscribe-component>

Properties and Attributes

This web component bridges HTML attributes and JavaScript properties to configure the underlying React component.

Configuration Methods

• HTML Attributes: Use for simple values (strings, booleans). Set directly in your HTML tag or using element.setAttribute(). Boolean attributes should be set as "true" or "false". JSON data should be passed as a valid JSON string.
• JavaScript Properties: Use for complex values (functions, objects). Set directly on the DOM element instance using JavaScript (e.g., element.handleReport = myFunction;).

Required Properties

| Attribute / Property | Configuration Type | JS Type | Description | | ------------------------- | ------------------ | -------------------------------------- | ------------------------------------------------------------------------- | | baseurl / baseUrl | HTML Attribute | string | Base URL for the SofIA API | | wssurl / wssUrl | HTML Attribute | string | Wss URL for the SofIA API | | apikey / apiKey | HTML Attribute | string | API key for authentication | | userid / userId | HTML Attribute | string | Your application's user identifier | | patientid / patientId | HTML Attribute | string | Your application's patient identifier | | toolsargs / toolsArgs | HTML Attribute | string (JSON) -> object | JSON string representing the tools configuration object | | handleReport | JS Property | (report: object) => void | Callback function invoked with the generated report data |

Optional Properties

| Attribute / Property | Configuration Type | JS Type | Description | | ------------------------------------------------------- | ------------------ | -------------------------------------- | ---------------------------------------------------------------------------- | | patientdata / patientData | HTML Attribute | string (JSON) -> object | Optional: JSON string with patient context data | | transcriptorselectvalues / transcriptorSelectValues | HTML Attribute | string (JSON) -> object | Optional: JSON string for transcriptor configuration (TTranscriptorSelect) | | renderReportContent | JS Property | TRenderReport (Function/ReactNode) | Optional: Custom function or ReactNode to render the report area | | toast | JS Property | TToastState | Optional: Initial toast state configuration object | | handleFill | JS Property | () => Promise<void> | Optional: Callback for fill action | | width | HTML Attribute | string | Width of the component (default: "600px") | | height | HTML Attribute | string | Height of the component (default: "650px") | | title | HTML Attribute | string | Title of the component | | language | HTML Attribute | string | Language code (e.g., "id", "ar", "en", "es") | | isscreenloading | HTML Attribute | string ("true"/"false") -> boolean | Screen loading indicator | | disableactions | HTML Attribute | string ("true"/"false") -> boolean | Disables actions in the component | | onlychat | HTML Attribute | string ("true"/"false") -> boolean | Disables transcriptor | | disablegenerate | HTML Attribute | string ("true"/"false") -> boolean | Disables generate and fill buttons | | chatsources | HTML Attribute | string (JSON) -> object | Optional: Array of transcriptor options with available chat | | isopen / isOpen | HTML Attribute | string ("true"/"false") -> boolean | Controls component visibility (show/hide) | | setIsOpen | JS Property | (isOpen: boolean) => void | Callback function invoked when the component requests a visibility change | | setGetLastReport | JS Property | (fn: () => Promise<unknown>) => void | Callback invoked with a function to retrieve the last generated report. |

Available chat sources

• Guías Clínicas
• Base de Datos de Medicamentos
• Estudios Científicos
• Base de Datos EMA
• Guías OMS
• Guías NICE
• Base de Datos FDA
• Guías CDC
• Vademecum
• Guías SEOM
• Guías AEP
• Guías SEC
• Guías SED
• Guías SEGO

Events

The component provides both property-based callbacks and event-based communication:

Property-Based Callbacks (Recommended)

Set these as JavaScript properties on the element:

• handleReport: Function called when report data is available
• setIsOpen: Function called when the component requests a visibility change

Event-Based Communication

The component dispatches custom events for framework integration:

| Event Name | event.detail | Description | | ----------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- | | handlereport / handle-report | object | Fired when report data is available (mirrors the handleReport property call) | | setisopen / set-is-open | boolean | Fired when the component requests a visibility change | | setgetlastreport / set-get-last-report | function | Fired with a function to retrieve the last generated report (mirrors the setGetLastReport property call) |

Global Event Handlers

For convenience, especially with frameworks like Angular, the component provides global event handlers:

• window.omniscribeHandleReport(report): Global function that dispatches handle-report events to all omniscribe components
• window.omniscribeSetIsOpen(isOpen): Global function that dispatches set-is-open events to all omniscribe components

Patient Data Structure

The patientdata attribute accepts a JSON string containing patient information. It's very important to add all the existing URL's that redirects to the patient information (medical history, consultations, medications, allergies, etc). Here's the expected structure:

interface PatientData {
  extraData?: extraData; // Additional information
  fullName?: string; // Patient's full name
  birthDate?: string; // Patient's birth date
  phone?: string; // Contact number
  address?: string; // Patient's address
}

interface extraData {
  patient_medical_notes?: { notes: object [] }; // Information about the medical notes of the patient
  medical_practice?: string; // Doctor medical practice
  // more information....
}

The component will use this information for the chat and patient context. All fields are optional, but providing more information will result in more detailed information.

Complete Example

<!DOCTYPE html>
<html>
  <head>
    <title>SofIA Web Component Example</title>
    <!-- Import the web component script (adjust path as needed) -->
    <script
      type="module"
      src="./node_modules/omniscribe-library/dist/webcomponents/index.js"
    ></script>
  </head>
  <body>
    <h1>SofIA Integration</h1>

    <button id="toggleBtn">Toggle SofIA</button>

    <!-- Set initial attributes directly in HTML -->
    <omniscribe-component
      id="sofia"
      baseurl="https://your-api.example.com"
      wssurl="https://your-wss.example.com"
      apikey="YOUR_API_KEY"
      userid="test-user-123"
      patientid="patient-abc-789"
      toolsargs='{"feature_flag": true}'
      isopen="true"
      patientdata='{"fullName": "Jane Doe", "birthDate": "1985-05-15"}'
      language="en"
      width="700px"
      height="600px"
      title="My Medical Assistant"
    >
    </omniscribe-component>

    <script>
      const sofIAElement = document.getElementById('sofia');
      const toggleBtn = document.getElementById('toggleBtn');

      let isSofIAOpen = true; // Your application's state for visibility

      // --- Set JS Properties (Functions/Objects) ---
      // These MUST be set via JavaScript after the element is in the DOM

      // Required: Handle report data
      sofIAElement.handleReport = report => {
        console.log('Report Received:', report);
        // Process the report object in your application
        alert('Report generated! Check the console.');
      };

      // Required: Handle visibility change requests from the component
      sofIAElement.setIsOpen = requestedState => {
        console.log(`SofIA requests visibility: ${requestedState}`);
        // Update your application state
        isSofIAOpen = requestedState;
        // Reflect the state change back to the component's attribute/property
        sofIAElement.isopen = isSofIAOpen; // Update property
        // OR: sofIAElement.setAttribute('isopen', isSofIAOpen.toString());
        toggleBtn.textContent = isSofIAOpen
          ? 'Hide SofIA'
          : 'Show SofIA';
      };

      // --- Control Visibility Externally (Example) ---
      toggleBtn.addEventListener('click', () => {
        isSofIAOpen = !isSofIAOpen;
        console.log(`Toggling visibility to: ${isSofIAOpen}`);
        // Update the component's property/attribute to show/hide it
        sofIAElement.isopen = isSofIAOpen; // Update property
        // OR: sofIAElement.setAttribute('isopen', isSofIAOpen.toString());
        toggleBtn.textContent = isSofIAOpen
          ? 'Hide SofIA'
          : 'Show SofIA';
      });

      // Initialize button text based on initial state
      toggleBtn.textContent = sofIAElement.isopen
        ? 'Hide SofIA'
        : 'Show SofIA';
    </script>
  </body>
</html>

👉 Need a complete example? Check the examples folder with ready-to-run Angular and Vanilla TypeScript implementations.

Examples

• Angular (TypeScript) → examples/angular-ts/
• Vanilla (TypeScript) → examples/vanilla-ts/

Run:

cd examples/angular-ts && npm start
# or
cd examples/vanilla-ts && npm run dev

Properties & Attributes

Required

| Name | Type | Description | |------|------|-------------| | baseUrl | string | Base URL for the Omniscribe API | | wssUrl | string | WebSocket endpoint | | apiKey | string | API key for authentication | | userId | string | Your application's user ID | | patientId | string | Your application's patient ID |

👉 See full documentation for optional properties like language, width, height, toolsArgs, and advanced callbacks.

Events

• handleReport(report) → Fired when report data is ready
• setIsOpen(isOpen) → Fired when visibility changes

👉 See the docs for a complete event reference and integration patterns.

Patient Data Structure

interface PatientData {
  extraData?: extraData;
  fullName?: string;
  birthDate?: string;
  phone?: string;
  address?: string;
}

interface extraData {
  patient_medical_notes?: { notes: object [] }; // Information about the medical notes of the patient
  medical_practice?: string; // Doctor medical practice
  // more information....
}

Features

• ✅ Real-time chat & medical transcription
• ✅ Report generation & regeneration
• ✅ Patient data integration
• ✅ Audio recording & transcription
• ✅ Multi-language support (en, es, ar, id)
• ✅ Shadow DOM encapsulation & styling

Troubleshooting

1. Verify required properties are set (baseUrl, wssUrl, apiKey, userId, patientId).
2. Ensure callbacks (handleReport, setIsOpen) are set after the element is in the DOM.
3. Validate JSON strings passed as attributes.
4. Check browser console for lifecycle logs and warnings.

Additional Resources

• 📚 Sofia Documentation – Complete solution docs (APIs, guides, compliance)
• 🏥 Commercial Licensing – Proprietary healthcare use
• 👥 Enterprise Support – Custom implementations & consulting

License

This project is dual-licensed:

• GNU AGPLv3 (open-source use)
• Commercial License (closed-source / SaaS use)

For commercial licensing, contact us.