= SPEC-001: Гібридна система AI Assistant для інтеграції з Medical Brain
:sectnums:
:toc:
:source-highlighter: rouge
:icons: font
:experimental:

== Background

Medical Brain (MB) є потужною rule-based системою, яка аналізує клінічні дані та генерує рекомендації для лікарів і пацієнтів. Хоча MB демонструє стабільність і швидкість прийняття рішень, її ефективність обмежується строго визначеними правилами, що не дозволяють враховувати всі контексти пацієнта.

Для подолання цих обмежень пропонується розробити AI Assistant, який інтегрується з MB, забезпечуючи:
- Постійний моніторинг рекомендацій MB.
- Контекстну перевірку точності на основі широкого спектру даних (історія хвороб, лабораторні результати, взаємодії у чатах).
- Блокування потенційно некоректних рекомендацій із сповіщенням лікарів.

Система буде реалізована поступово з можливістю масштабування до більш складних функцій. Основні задачі: підвищення точності, безпеки, ефективності та гнучкості роботи MB.

== Requirements

Вимоги до системи AI Assistant для інтеграції з Medical Brain (MB) структуровані за методологією MoSCoW.

=== Must-have (Обов'язкові)
1. Постійний моніторинг рекомендацій MB у реальному часі.
2. Зіставлення рекомендацій MB з клінічними даними пацієнта, включаючи:
   - Історію хвороб.
   - Лабораторні результати.
   - Поточний стан пацієнта.
3. Блокування некоректних рекомендацій MB до їхньої передачі лікарю чи пацієнту.
4. Генерація сповіщень до Supervisor Module у випадку виявлення помилок або невідповідностей.
5. Інтеграція з базою даних EHR для збереження та обробки даних пацієнта.
6. Підтримка механізмів Retrieval-Augmented Generation (RAG) для оптимізації використання ресурсів.

=== Should-have (Бажані)
1. Режими пам'яті (постійна й оперативна) для ефективного управління даними пацієнта.
2. Аналіз текстової взаємодії у чатах між пацієнтами й лікарями.
3. Масштабованість до Level 2 (рекомендації лікарям) і Level 3 (рекомендації пацієнтам).
4. Логування всіх дій системи для забезпечення трасування помилок.

=== Could-have (Можливі)
1. Зворотній зв'язок із лікарями для покращення моделей AI.
2. Кешування рекомендацій для підвищення швидкості.
3. Інтеграція з зовнішніми AI-платформами для вдосконалення моделей.

=== Won't-have (Виключення)
1. Пряма взаємодія з пацієнтами (поза межами рівнів, визначених системою).
2. Прогнозування складних сценаріїв без додаткового тестування й пілотування.

== Method

=== Архітектура системи

Система AI Assistant складається з таких основних компонентів:

[plantuml]
----
@startuml
!define RECTANGLE #White
rectangle "Medical Brain (MB)" as MB
rectangle "AI Assistant" as Assistant {
    rectangle "LLM API\n(External Service)" as LLM_API
    rectangle "Prompt Formation\nand Caching Module" as Prompt_Module
    rectangle "Memory Module\n(Permanent/Operational)" as Memory_Module
}
rectangle "EHR Database" as EHR
rectangle "Supervisor Module" as Supervisor

MB --> Assistant: MB Recommendations
Assistant --> Supervisor: Notifications
LLM_API --> Assistant: Results
EHR --> Memory_Module: Patient Data
Prompt_Module --> LLM_API: Optimized Queries
Memory_Module --> Prompt_Module: Context
@enduml
----

=== Основні компоненти:

1. **Medical Brain (MB)**
   Використовує rule-based логіку для первинного аналізу даних пацієнта та формування рекомендацій.

2. **AI Assistant**
   Виконує розширений аналіз і перевірку рекомендацій MB.
   - Взаємодія з LLM через зовнішнє API для отримання текстових відповідей на основі контексту.
   - Формування оптимізованих prompts із використанням:
     - Постійної пам'яті (історія хвороб, хронічні захворювання, протоколи лікування).
     - Оперативної пам'яті (актуальні дані за останні 24–48 годин).
   - Кешування повторюваних частин prompts для зменшення витрат.

3. **Модуль формування prompts**
   - Генерує prompts для запитів до LLM, які враховують:
     - Персоналізацію для конкретного пацієнта.
     - Медичний контекст (включно з протоколами лікування).
   - Кешує частини prompts, які не змінюються між запитами, наприклад:
     - Загальні дані пацієнта (ім'я, хронічні стани).
     - Протоколи лікування для спеціалізованих напрямків.

4. **Модуль пам'яті**
   - **Постійна пам'ять**:
     - Інтегрується з EHR для зберігання ключової інформації про пацієнта.
     - Може використовувати RAG для динамічного отримання додаткових даних із протоколів лікування чи баз знань.
   - **Оперативна пам'ять**:
     - Реалізує ковзне вікно останніх подій, включно з взаємодіями у чатах і змінами стану пацієнта.

5. **Supervisor Module**
   Виконує роль наглядача для контролю роботи MB і AI Assistant.
   - Отримує нотифікації про виявлені помилки чи невідповідності.
   - Підтримує інтерактивний інтерфейс для лікарів-контролерів.

6. **LLM API**
   - Зовнішній сервіс для обробки текстових запитів.
   - Підтримує великий контекстний обсяг (long-context window).
   - Інтегрується через REST або gRPC API.

=== Алгоритм роботи:

1. **Збір даних**
   - Дані з EHR інтегруються до постійної пам'яті через модуль пам'яті.
   - Поточні події додаються до оперативної пам'яті в реальному часі.

2. **Формування запиту (prompt)**
   - AI Assistant генерує запит до LLM, використовуючи:
     - Кешовані статичні частини (загальні дані пацієнта, протоколи лікування).
     - Динамічний контекст (поточні події, стан пацієнта).

3. **Використання RAG**
   - За потреби дані для запиту отримуються з довготривалої пам'яті або баз знань.
   - LLM формує відповідь, враховуючи релевантні матеріали.

4. **Аналіз рекомендацій MB**
   - AI Assistant перевіряє відповідність рекомендацій MB протоколам і загальному контексту.
   - Некоректні рекомендації блокуються, а сповіщення надсилаються до Supervisor Module.

5. **Кешування**
   - Частини prompts, що залишаються незмінними між запитами, кешуються для оптимізації.

6. **Нотифікація Supervisor Module**
   - У разі виявлення невідповідностей формується нотифікація з деталями проблеми.

=== Візуалізація

[plantuml]
----
@startuml
rectangle "Long-term Memory (EHR)" as LongMemory
rectangle "Short-term Memory (Operational)" as ShortMemory
rectangle "RAG Module" as RAG
rectangle "Context Caching" as Cache
rectangle "LLM API" as LLM

LongMemory --> Cache : Static Data Caching
ShortMemory --> Cache : Dynamic Data Updates
RAG --> Cache : Loading Specific Knowledge
Cache --> LLM : Prompt Formation
LLM --> AI_Assistant : Analysis Result
@enduml
----