CURRENT_ARCHITECTURE.md

# 🏗️ Поточна архітектура Lifestyle Journey

## 🎯 Огляд системи

**Lifestyle Journey** - медичний чат-бот з lifestyle коучингом на базі Gemini API, що використовує розумну класифікацію повідомлень та м'який медичний тріаж.

## 🔧 Ключові компоненти

### 📋 Класифікатори

#### 1. **EntryClassifier** - K/V/T формат
**Призначення:** Класифікує повідомлення пацієнта на початку взаємодії

**Формат відповіді:**
```json
{
    "K": "Lifestyle Mode",
    "V": "on|off|hybrid", 
    "T": "2025-09-04T11:30:00Z"
}
```

**Значення V:**
- **off** - медичні скарги, симптоми, вітання → м'який медичний тріаж
- **on** - lifestyle питання → активація lifestyle режиму
- **hybrid** - містить і lifestyle теми, і медичні скарги → гібридний потік

#### 2. **TriageExitClassifier**
**Призначення:** Після медичного тріажу оцінює готовність до lifestyle

**Критерії для lifestyle:**
- Медичні скарги стабілізовані
- Пацієнт готовий до lifestyle активностей
- Немає активних симптомів

#### 3. **LifestyleExitClassifier** (deprecated)
**Призначення:** Контролює вихід з lifestyle режиму
**Статус:** Замінено на MainLifestyleAssistant логіку

### 🤖 Асистенти

#### 1. **SoftMedicalTriage** - М'який тріаж
**Призначення:** Делікатна перевірка стану пацієнта на початку взаємодії

**Принципи:**
- Дружній, не нав'язливий тон
- 1-2 коротких питання про самопочуття
- Швидка оцінка потреби в медичній допомозі
- Готовність перейти до lifestyle якщо все добре

#### 2. **MedicalAssistant** - Повний медичний режим
**Призначення:** Медичні консультації з урахуванням хронічних станів

**Функції:**
- Безпечні рекомендації та тріаж
- Направлення до лікарів при red flags
- Урахування медичного анамнезу та медикаментів

#### 3. **MainLifestyleAssistant** - Розумний lifestyle коуч
**Призначення:** Аналізує повідомлення і визначає найкращу дію для lifestyle сесії

**3 типи дій:**
```json
{
    "message": "відповідь пацієнту",
    "action": "gather_info|lifestyle_dialog|close",
    "reasoning": "пояснення вибору дії"
}
```

- **gather_info** - збір додаткової інформації про стан, уподобання
- **lifestyle_dialog** - lifestyle коучинг та рекомендації  
- **close** - завершення lifestyle сесії (медичні скарги, прохання, довга сесія)

### 🔄 Менеджери

#### **LifestyleSessionManager**
**Призначення:** Управляє lifecycle lifestyle сесій та розумно оновлює профіль

**Функції:**
- Суммаризація сесії без розростання даних
- Контроль розміру `journey_summary` (максимум 800 символів)
- Логування ключових моментів з датами
- Уникнення повторів інструкцій

## 🔄 Потік обробки повідомлень

### 1. **Entry Classification**
```
Повідомлення → EntryClassifier → K/V/T формат
├── V="off" → SoftMedicalTriage
├── V="on" → MainLifestyleAssistant  
└── V="hybrid" → Гібридний потік
```

### 2. **Гібридний потік**
```
V="hybrid" → MedicalAssistant (тріаж)
           → TriageExitClassifier (оцінка готовності)
           → [lifestyle або medical режим]
```

### 3. **Lifestyle режим**
```
MainLifestyleAssistant → action
├── "gather_info" → збір інформації (продовжити lifestyle)
├── "lifestyle_dialog" → коучинг (продовжити lifestyle)
└── "close" → завершення → LifestyleSessionManager → medical режим
```

### 4. **Оновлення профілю**
```
Завершення lifestyle → LifestyleSessionManager
                    → Аналіз сесії
                    → Оновлення last_session_summary
                    → Додавання до journey_summary
                    → Контроль розміру даних
```

## 📊 Структура даних

### **SessionState**
```python
@dataclass
class SessionState:
    current_mode: str                    # "medical" | "lifestyle" | "none"
    is_active_session: bool
    session_start_time: Optional[str]
    last_controller_decision: Dict
    lifestyle_session_length: int = 0   # Лічильник lifestyle повідомлень
    last_triage_summary: str = ""        # Результат медичного тріажу
    entry_classification: Dict = None    # K/V/T класифікація
```

### **Приклад оновлення профілю**
```json
{
  "last_session_summary": "[04.09.2025] Обговорювали: питання про ходьбу; дієта з низьким вмістом солі",
  "journey_summary": "...попередні записи... | 04.09.2025: 5 повідомлень"
}
```

## 🎯 Переваги поточної архітектури

### 1. **K/V/T формат**
- Простіший для розуміння ніж складні категорії
- Легше розширювати в майбутньому
- Консистентний timestamp для відстеження

### 2. **М'який медичний тріаж**
- Делікатніший підхід до пацієнтів
- Природні відповіді на вітання
- Не лякає одразу повним медичним режимом

### 3. **Розумний lifestyle асистент**
- Сам визначає коли збирати інформацію
- Сам вирішує коли давати поради
- Сам визначає коли завершувати сесію
- Менше API викликів

### 4. **Контрольоване оновлення профілю**
- Уникає розростання даних
- Зберігає тільки ключову інформацію
- Контролює розмір journey_summary

## 🧪 Тестування

### **Покриття тестами:**
- ✅ Entry Classifier K/V/T: 8/8
- ✅ Main Lifestyle Assistant: 7/7
- ✅ Lifecycle потоки: 3/3
- ✅ Profile Update: працює
- ✅ Всього тестів: 31/31

### **Тестові сценарії:**
```python
# K/V/T класифікація
"У мене болить голова" → V="off"
"Хочу почати займатися спортом" → V="on"
"Хочу займатися спортом, але у мене болить спина" → V="hybrid"
"Привіт" → V="off" (м'який тріаж)

# Main Lifestyle дії
"Хочу почати займатися спортом" → action="gather_info"
"Дайте мені поради щодо харчування" → action="lifestyle_dialog"
"У мене болить спина" → action="close"
```

## 🚀 Деплой та використання

### **Файли системи:**
```
├── app.py                    # Точка входу з create_app()
├── huggingface_space.py      # HuggingFace Space entry point
├── lifestyle_app.py          # Основна бізнес-логіка
├── core_classes.py           # Класифікатори та асистенти
├── prompts.py                # Промпти для Gemini API
├── gradio_interface.py       # UI інтерфейс
├── requirements.txt          # Залежності
└── README.md                 # Документація для HF Space
```

### **Змінні оточення:**
```bash
GEMINI_API_KEY=your_api_key    # Обов'язково
LOG_PROMPTS=true               # Опціонально для debug
```

### **Запуск:**
```bash
# Локально
python app.py

# HuggingFace Space
# Автоматично через huggingface_space.py
```

## 📈 Метрики та моніторинг

### **Автоматично відстежується:**
- Кількість API викликів до Gemini
- Розподіл по режимах (medical/lifestyle)
- Тривалість lifestyle сесій
- Частота оновлень профілю

### **Логування (LOG_PROMPTS=true):**
- Всі промпти до Gemini API з типом виклику
- Повні відповіді LLM з timestamps
- Класифікаційні рішення та обґрунтування
- Метрики продуктивності

## 🔮 Майбутні покращення

### **Короткострокові:**
- Покращення розпізнавання прохань про завершення
- Додавання timeout для lifestyle сесій
- Оптимізація промптів на основі реальних тестів

### **Довгострокові:**
- Додавання нових типів класифікації
- Інтеграція з медичними системами
- Персоналізація на основі історії взаємодій
- A/B тестування різних підходів

---

**Система готова до продакшену з чистою архітектурою та розумною логікою!** 🚀