docs/PROMPT_EDITING.md

# Редагування промптів - Документація

## Огляд

Додано можливість редагування промптів з повною ізоляцією сесій для безпечної роботи на хмарних серверах (наприклад, Hugging Face Spaces).

## Основні можливості

### 1. Ізоляція сесій користувачів

Кожен користувач отримує унікальний session ID при відкритті додатку:
- Session ID генерується автоматично при завантаженні інтерфейсу
- Всі дані користувача (правові позиції, результати пошуку, налаштування промптів) зберігаються в ізольованій сесії
- Сесії автоматично видаляються після 30 хвилин неактивності (налаштовується в config)

### 2. Редагування промптів

У вкладці "⚙️ Налаштування" користувачі можуть редагувати три типи промптів:

#### 📋 Системний промпт
Визначає роль та базові інструкції для AI.
- За замовчуванням: "Ти - кваліфікований юрист-аналітик..."
- Впливає на всі операції з AI

#### ⚖️ Промпт генерації правової позиції
Шаблон для генерації правової позиції з судового рішення.
- Містить плейсхолдери: `{court_decision_text}` та `{comment}`
- Впливає на формат та зміст згенерованих правових позицій

#### 🔍 Промпт аналізу прецедентів
Шаблон для порівняльного аналізу правових позицій.
- Містить плейсхолдери: `{query}`, `{question}`, `{context_str}`
- Впливає на аналіз релевантності знайдених позицій

### 3. Операції з промптами

#### 💾 Зберегти промпти
- Зберігає всі три промпти в сесію користувача
- Валідація: максимум 50,000 символів на промпт
- Повідомлення про успішне збереження

#### 🔄 Скинути до стандартних
- Відновлює всі промпти до початкових значень
- Оновлює відображення в полях редагування

## Архітектура

### Компоненти

```
src/session/
├── state.py       - UserSessionState з полем custom_prompts
├── manager.py     - SessionManager для управління сесіями
└── storage.py     - Зберігання (Memory/Redis)

interface.py       - UI з вкладкою "Налаштування" + інтеграція з сесіями
main.py            - generate_legal_position() приймає кастомні промпти
prompts.py         - Стандартні промпти (fallback)
```

### Потік даних

1. **Завантаження додатку**
   - Генерується session_id (UUID4)
   - Створюється нова сесія в SessionManager
   - Завантажуються промпти (кастомні або стандартні)

2. **Редагування промптів**
   - Користувач змінює текст у полях редагування
   - Натискає "💾 Зберегти промпти"
   - Промпти зберігаються в `session.custom_prompts`
   - SessionManager оновлює сесію в storage

3. **Генерація правової позиції**
   - Отримує session_id з Gradio State
   - Завантажує сесію з SessionManager
   - Витягує кастомні промпти через `session.get_prompt()`
   - Передає промпти в `generate_legal_position()`
   - LLM використовує кастомні промпти
   - Результат зберігається в сесію

4. **Закінчення сесії**
   - Автоматична очистка після 30 хв неактивності
   - Background task в SessionManager видаляє застарілі сесії

## Налаштування

### config/environments/default.yaml

```yaml
session:
  timeout_minutes: 30              # Таймаут сесії
  cleanup_interval_minutes: 5      # Інтервал очистки
  max_sessions: 1000               # Максимум активних сесій
  storage_type: "memory"           # "memory" або "redis"
```

### Для production (Redis)

```yaml
session:
  storage_type: "redis"

redis:
  host: "localhost"
  port: 6379
  db: 0
  password: null
```

## Безпека

### Ізоляція користувачів

✅ **Гарантовано:**
- Кожен користувач має унікальний session_id
- Дані зберігаються окремо для кожної сесії
- Неможливо отримати доступ до даних іншого користувача

### Валідація промптів

✅ **Захист:**
- Обмеження довжини промптів (50,000 символів)
- Очистка застарілих сесій (захист від витоку пам'яті)
- Логування всіх операцій з сесіями

### Відсутність персистентності промптів

⚠️ **Важливо:**
- Кастомні промпти зберігаються тільки на час сесії
- Після таймауту (30 хв) промпти скидаються
- Для збереження промптів назавжди - потрібно додати функціонал експорту/імпорту

## Приклади використання

### Зміна тону відповідей

**Стандартний системний промпт:**
```
Ти - кваліфікований юрист-аналітик, експерт з правових позицій Верховного Суду.
```

**Кастомний (більш формальний):**
```
Ви - висококваліфікований експерт-правознавець з міжнародним досвідом аналізу
судової практики Верховного Суду України. Дотримуйтесь найвищих стандартів
юридичної точності та академічної строгості.
```

### Додавання інструкцій для конкретного типу справ

**Стандартний промпт генерації:**
```
Дотримуйся цих інструкцій...
```

**Кастомний (для цивільних справ):**
```
Дотримуйся цих інструкцій.

ДОДАТКОВІ ВИМОГИ ДЛЯ ЦИВІЛЬНИХ СПРАВ:
1. Обов'язково виділяй позиції щодо процесуальних питань
2. Зазначай застосовані норми ЦПК України
3. Вказуй склад суду та рівень юрисдикції
...
```

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

### Перевірка ізоляції сесій

1. Відкрийте додаток у двох різних браузерах/вкладках
2. У першій вкладці: змініть системний промпт на "Тест 1"
3. У другій вкладці: змініть системний промпт на "Тест 2"
4. Збережіть в обох вкладках
5. Згенеруйте правову позицію в обох вкладках
6. ✅ Кожна вкладка повинна використовувати свій промпт

### Перевірка persistance

1. Змініть та збережіть промпти
2. Згенеруйте правову позицію (перевірте, що використовуються кастомні промпти)
3. Зачекайте 31 хвилину (або змініть timeout в конфігурації)
4. ✅ Сесія має бути очищена, промпти скинуті до стандартних

## Подальший розвиток

### Планується додати:

1. **Експорт/імпорт промптів**
   - Збереження у JSON/YAML файли
   - Завантаження збережених наборів промптів

2. **Бібліотека шаблонів**
   - Готові набори промптів для різних типів справ
   - Спільнота користувачів може ділитися промптами

3. **Версіонування промптів**
   - Історія змін промптів
   - Можливість відкоту до попередніх версій

4. **A/B тестування**
   - Порівняння результатів з різними промптами
   - Метрики якості генерації

5. **Адміністративна панель**
   - Глобальні промпти для всіх користувачів
   - Статистика використання різних промптів

## Troubleshooting

### Промпти не зберігаються

**Проблема:** Після збереження промптів вони не застосовуються

**Рішення:**
1. Перевірте console в браузері на помилки JavaScript
2. Перевірте логи додатку на помилки Session Manager
3. Переконайтесь, що session_id правильно передається між функціями

### Промпти скидаються занадто швидко

**Проблема:** Сесія закривається раніше 30 хвилин

**Рішення:**
1. Перевірте `config/environments/default.yaml` -> `session.timeout_minutes`
2. Збільште значення таймауту
3. Перезапустіть додаток

### Помилки при використанні кастомних промптів

**Проблема:** LLM повертає помилку або неправильний формат

**Рішення:**
1. Переконайтесь, що промпт містить необхідні плейсхолдери:
   - `{court_decision_text}` і `{comment}` для генерації
   - `{query}`, `{question}`, `{context_str}` для аналізу
2. Перевірте довжину промпту (не більше 50,000 символів)
3. Скиньте промпти до стандартних і перевірте, чи працює базовий функціонал

## Технічні деталі

### UserSessionState.custom_prompts

```python
custom_prompts: Dict[str, str] = {
    'system': str,           # Системний промпт
    'legal_position': str,   # Промпт генерації
    'analysis': str          # Промпт аналізу
}
```

### Методи роботи з промптами

```python
# Отримання промпту (з fallback)
prompt = session.get_prompt('system', DEFAULT_SYSTEM_PROMPT)

# Встановлення промпту
session.set_prompt('system', new_prompt)

# Скидання всіх промптів
session.reset_prompts()
```

### Інтеграція з генерацією

```python
def generate_legal_position(
    # ...існуючі параметри...
    custom_system_prompt: Optional[str] = None,
    custom_lp_prompt: Optional[str] = None
) -> Dict:
    # Використання кастомних або стандартних промптів
    system_prompt = custom_system_prompt or SYSTEM_PROMPT
    lp_prompt = custom_lp_prompt or LEGAL_POSITION_PROMPT

    # Генерація з кастомними промптами
    # ...
```

## Підсумок

Нова функціональність редагування промптів забезпечує:

✅ Повну ізоляцію між користувачами
✅ Безпечну роботу на хмарних серверах
✅ Гнучке налаштування AI під конкретні потреби
✅ Автоматичну очистку застарілих даних
✅ Простий та інтуїтивний інтерфейс

Система готова до production використання на Hugging Face Spaces та інших платформах.