HELP.md

# 📖 Довідка - AI Асистент для роботи з правовими позиціями

## Зміст

1. [Огляд додатку](#огляд-додатку)
2. [Закладка: Генерація](#закладка-генерація)
3. [Закладка: Пошук](#закладка-пошук)
4. [Закладка: Аналіз](#закладка-аналіз)
5. [Закладка: Налаштування](#закладка-налаштування)
6. [Закладка: Пакетне тестування](#закладка-пакетне-тестування)
7. [Підтримувані провайдери](#підтримувані-провайдери)
8. [Часті питання](#часті-питання)
9. [Поради та рекомендації](#поради-та-рекомендації)

---

## Огляд додатку

**AI Асистент** - це інтелектуальний інструмент для роботи з правовими позиціями Верховного Суду України. Додаток використовує сучасні AI моделі (GPT, Claude, Gemini, DeepSeek) для автоматичної генерації, пошуку та аналізу правових позицій.

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

- ✅ **Генерація** правових позицій з текстів судових рішень
- ✅ **Пошук** схожих позицій у базі даних Верховного Суду
- ✅ **Аналіз** релевантності знайдених позицій
- ✅ **Налаштування** промптів для персоналізації роботи AI
- ✅ **Пакетне тестування** для масової обробки даних

---

## Закладка: Генерація

### Призначення
Автоматичне формування проекту правової позиції з тексту судового рішення.

### Як користуватися:

#### 1. Вибір провайдера та моделі
- **Провайдер AI**: Оберіть постачальника AI (OpenAI, Anthropic, Gemini, DeepSeek)
- **Модель генерації**: Виберіть конкретну модель (наприклад, GPT-4o, Claude 3.5 Sonnet, Gemini 3.0 Flash)

**Рекомендації:**
- Для швидкої роботи: Gemini 3.0 Flash, GPT-5 Mini, GPT-4o-mini
- Для якісних результатів: GPT-5.2, Claude Sonnet 4.6, GPT-4o
- Для економії: DeepSeek Chat

#### 2. Додаткові параметри (Температура, Thinking Mode, Verbosity)
- **Температура генерації**: дозволяє налаштовувати креативність моделі від 0.0 (строга) до 2.0 (креативна).
- **Режим Thinking (для OpenAI GPT-5+, Gemini 3+ та Claude 4.5/4.6)**: 
  - Увімкніть для глибшого аналізу складних рішень.
- **Тип Thinking (Claude)**:
  - **Adaptive**: модель сама обирає глибину міркувань (працює для моделей 4.6).
  - **Enabled**: класичний режим із жорстким бюджетом токенів (для моделей 4.5 та 4.6).
- **Рівні Thinking (OpenAI / Gemini)**: none → low → medium → high → xhigh (у GPT-5.2)
- **Verbosity (OpenAI GPT-5)**: керування багатослівністю (low, medium, high)
- **Бюджет токенів (Claude 4.5 або Enabled)**: 1024-32000

#### 3. Спосіб вводу даних

**Варіант А: Текстовий ввід**
- Вставте текст судового рішення безпосередньо
- Найшвидший спосіб
- Підходить для коротких текстів

**Варіант Б: URL посилання**
- Вставте посилання на рішення з reyestr.court.gov.ua
- Автоматичне витягування тексту
- Зручно для онлайн-рішень

**Варіант В: Завантаження файлу**
- Завантажте TXT файл з текстом рішення
- Підходить для збережених локально рішень
- Підтримка UTF-8 та CP1251

#### 4. Коментар (опціонально)
Додайте уточнення для AI, наприклад:
- "Звернути увагу на процесуальні питання"
- "Виділити позиції щодо строків позовної давності"
- "Акцентувати на нормах ЦПК України"

#### 5. Генерація
Натисніть **"📝 Генерувати проект правової позиції"**

### Результат генерації:

Ви отримаєте структуровану правову позицію з:
- **Заголовок** - коротка назва позиції
- **Текст** - зміст правової позиції
- **Тип судочинства** - кримінальне, цивільне, господарське, адміністративне
- **Категорія** - тематична класифікація

### Час обробки:
- Швидкі моделі: 5-15 секунд
- Потужні моделі: 15-30 секунд
- З режимом Thinking: 30-60 секунд

---

## Закладка: Пошук

### Призначення
Знайти схожі правові позиції Верховного Суду у базі даних.

### Два типи пошуку:

#### 1. Пошук на основі правової позиції
- Використовує згенеровану позицію з закладки "Генерація"
- **Коли використовувати**: після генерації позиції
- **Як активувати**: кнопка стає доступною після генерації
- Натисніть **"🔎 Пошук на основі правової позиції"**

#### 2. Пошук на основі вхідного тексту
- Використовує оригінальний текст судового рішення
- **Коли використовувати**: для швидкого пошуку без генерації
- **Як активувати**: доступна завжди
- Натисніть **"🔎 Пошук на основі вхідного тексту"**

### Результати пошуку:

Ви отримаєте список релевантних позицій з:
- **Номер** у списку [1], [2], [3]...
- **Заголовок** правової позиції
- **Посилання** на позицію та судове рішення
- **Score** - показник релевантності (чим вище, тим краще)

### Технологія пошуку:
- Гібридний підхід: векторний пошук + BM25
- Автоматична дедуплікація результатів
- Топ-10 найрелевантніших позицій

---

## Закладка: Аналіз

### Призначення
Детальний порівняльний аналіз знайдених правових позицій.

### Як користуватися:

#### 1. Попередні кроки
⚠️ Спочатку потрібно виконати пошук у закладці "Пошук"

#### 2. Вибір моделі аналізу та налаштувань
- Оберіть провайдер та модель для аналізу
- Рекомендовано: GPT-5.2, Claude Sonnet 4.6
- **Температура аналізу**: налаштування креативності порівняння.
- **Max Tokens (ліміт відповіді)**: максимальний обсяг деталізації аналізу (від 512 до 32768).

#### 3. Уточнююче питання (опціонально)
Додайте конкретне питання для AI, наприклад:
- "Чи підходять ці позиції для справ про відшкодування моральної шкоди?"
- "Які з позицій стосуються процесуальних питань?"
- "Чи є позиції щодо застосування норм ЦКУ?"

#### 4. Запуск аналізу
Натисніть **"⚖️ Аналіз результатів пошуку"**

### Результат аналізу:

Для кожної релевантної позиції ви отримаєте:
- **Номер позиції** у списку
- **Детальне обґрунтування** релевантності
- **Аналіз спільних аспектів** з вашим рішенням
- **Рекомендації** щодо застосування

### Час обробки:
- Залежить від кількості знайдених позицій
- 1-3 позиції: 15-30 секунд
- 5-10 позицій: 30-60 секунд

---

## Закладка: Налаштування

### Призначення
Персоналізація промптів для AI відповідно до ваших потреб.

### Три типи промптів:

#### 1. Системний промпт
**Що це:** Визначає роль та базові інструкції для AI

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

**Коли змінювати:**
- Для зміни стилю відповідей (формальний, академічний)
- Для додавання спеціалізації (цивільне право, кримінальне)

#### 2. Промпт генерації правової позиції
**Що це:** Шаблон для створення правових позицій з судових рішень

**Важливо:** Містить плейсхолдери:
- `{court_decision_text}` - текст рішення
- `{comment}` - ваш коментар

**Коли змінювати:**
- Для зміни структури позиції
- Для додавання специфічних вимог
- Для фокусу на певних аспектах

#### 3. Промпт аналізу прецедентів
**Що це:** Шаблон для порівняльного аналізу позицій

**Важливо:** Містить плейсхолдери:
- `{query}` - нова позиція
- `{question}` - уточнююче питання
- `{context_str}` - знайдені позиції

**Коли змінювати:**
- Для зміни критеріїв аналізу
- Для глибшого порівняння

### Як редагувати:

1. Відредагуйте текст промпту у відповідному полі
2. Натисніть **"💾 Зберегти промпти"**
3. Побачите підтвердження: ✅ "Промпти успішно збережено"
4. Поверніться до генерації - тепер використовуються ваші промпти!

### Скинути до стандартних:

Натисніть **"🔄 Скинути до стандартних"** для повернення дефолтних промптів.

### Важливо:
- Промпти зберігаються тільки для вашої сесії
- Час сесії: 30 хвилин без активності
- Кожен користувач має свої власні промпти
- Повна ізоляція між користувачами

---

## Закладка: Пакетне тестування

### Призначення
Масова генерація правових позицій з CSV файлів для тестування та порівняння моделей.

### Покрокова інструкція:

#### Крок 1: Підготовка CSV файлу

Створіть CSV файл з обов'язковою колонкою `text`:

```csv
id_lp,text
1,"Текст судового рішення 1..."
2,"Текст судового рішення 2..."
3,"Текст судового рішення 3..."
```

**Приклади:** дивіться `test_docs/test_sample.csv`

#### Крок 2: Налаштування параметрів

1. **Провайдер AI** - оберіть постачальника (OpenAI, Anthropic, Gemini, DeepSeek)
2. **Модель генерації** - виберіть модель для тестування
3. **Пауза між запитами** - встановіть затримку (0-10 секунд)

**Рекомендовані паузи:**
- 1-10 рядків: 0.5-1 сек
- 10-50 рядків: 1-2 сек
- 50-100 рядків: 2-3 сек
- 100+ рядків: 3-5 сек

#### Крок 3: Завантаження файлу

1. Натисніть **"📁 Завантажте CSV файл з тестовими даними"**
2. Виберіть ваш CSV файл
3. Натисніть **"📂 Завантажити CSV файл"**
4. Перевірте попередній перегляд:
   - Кількість рядків
   - Список колонок
   - Перші 3 рядки тексту

#### Крок 4: Запуск тестування

1. Натисніть **"▶️ Запустити пакетне тестування"**
2. Слідкуйте за прогресом:
   - Прогрес-бар показує поточний стан
   - "Обробка рядка X з Y"

#### Крок 5: Завантаження результатів

Після завершення:
1. З'явиться кнопка **"📥 Завантажити результати"**
2. Файл збережено у `test_results/`
3. Назва файлу: `batch_test_results_{модель}_{дата_час}.csv`

### Формат результатів:

Результуючий CSV містить:
- Всі оригінальні колонки
- Нова колонка з назвою моделі
- У новій колонці - **повний JSON об'єкт**:

```json
{
    "title": "Заголовок правової позиції",
    "text": "Текст правової позиції",
    "proceeding": "Тип судочинства",
    "category": "Категорія"
}
```

### Обробка результатів у Python:

```python
import pandas as pd
import json

# Завантажити результати
df = pd.read_csv('test_results/batch_test_results_gemini-3.0-flash_20260103_120000.csv')

# Парсити JSON
df['parsed'] = df['gemini-3.0-flash'].apply(json.loads)

# Витягти поля
df['title'] = df['parsed'].apply(lambda x: x['title'])
df['text'] = df['parsed'].apply(lambda x: x['text'])
```

### Час виконання:

**Розрахунок:** `кількість_рядків × (час_запиту + пауза)`

**Приклади:**
- 10 рядків × (3 сек + 1 сек) = ~40 секунд
- 100 рядків × (3 сек + 1 сек) = ~6.7 хвилин

### Поради:
- Для великих обсягів (100+ рядків) використовуйте паузу 3-5 сек
- При помилках rate limit - збільште паузу
- Результати зберігаються автоматично навіть при помилках окремих рядків

---

## Підтримувані провайдери

### OpenAI

**Моделі:**
- GPT-5.2 - остання потужна модель (рекомендована)
- GPT-5 Mini - швидка і потужна модель нового покоління
- GPT-4o - попередня потужна модель
- GPT-4o-mini - баланс ціна/якість
- GPT-4.1 - версія GPT-4 (reasoning)
- Fine-tuned моделі - власні налаштовані моделі

**Особливості:**
- Швидка обробка
- Підтримка Reasoning Effort (до `xhigh` в GPT-5.2) та Verbosity
- Висока якість структурованих даних (JSON Schema)

**API Key:** `OPENAI_API_KEY`

### Anthropic (Claude)

**Моделі:**
- Claude Sonnet 4.6 - рекомендована (за замовчуванням)
- Claude Opus 4.6 - найпотужніша
- Claude Haiku 4.5 - швидка модель

**Особливості:**
- Детальний аналіз та структурування
- **Adaptive Thinking** у серії 4.6 для гнучкого використання ресурсів
- **Extended Thinking** у серії 4.5 для складних завдань
- Великий контекст

**API Key:** `ANTHROPIC_API_KEY`

### Google (Gemini)

**Моделі:**
- Gemini 3.0 Flash - швидка
- Gemini 3.5 Flash - з Thinking Mode
- Gemini 2.0 Flash - експериментальна

**Особливості:**
- Thinking Mode для глибокого аналізу
- Безкоштовний tier
- Швидка обробка

**API Key:** `GEMINI_API_KEY`

### DeepSeek

**Моделі:**
- DeepSeek Chat - універсальна

**Особливості:**
- Низька ціна
- Хороша якість
- Підтримка українською

**API Key:** `DEEPSEEK_API_KEY`

---

## Часті питання

### Загальні питання

**Q: Чи потрібна реєстрація?**
A: Ні, додаток працює без реєстрації. Кожна сесія автоматично ідентифікується.

**Q: Скільки коштує використання?**
A: Додаток безкоштовний, оплачується тільки API провайдерів (якщо використовуєте платні моделі).

**Q: Чи зберігаються мої дані?**
A: Дані зберігаються тільки на час сесії (30 хвилин). Після закриття - автоматично видаляються.

**Q: Чи можуть інші користувачі бачити мої промпти?**
A: Ні, повна ізоляція між користувачами. Кожна сесія унікальна.

### Генерація

**Q: Яку модель обрати?**
A: Для початку - Gemini 3.0 Flash (безкоштовно) або GPT-4o-mini (дешево).

**Q: Чому генерація повільна?**
A: Залежить від моделі і режиму Thinking. Вимкніть Thinking для швидшої роботи.

**Q: Що робити з URL, які не працюють?**
A: Скопіюйте текст вручну та вставте як "Текстовий ввід".

### Пошук

**Q: Чому мало результатів?**
A: База містить тільки позиції Верховного Суду. Не всі теми представлені.

**Q: Що означає Score?**
A: Показник схожості (0-1). Чим вище - тим релевантніше.

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

**Q: Промпти не працюють після збереження**
A: Перевірте наявність плейсхолдерів `{court_decision_text}` і `{comment}`.

**Q: Чи можу я зберегти промпти назавжди?**
A: Поки що ні - тільки на час сесії. Скопіюйте їх у файл для збереження.

### Пакетне тестування

**Q: Який максимальний розмір CSV?**
A: Технічно необмежений, але рекомендовано до 500 рядків за раз.

**Q: Що робити при помилках rate limit?**
A: Збільште паузу між запитами до 3-5 секунд.

**Q: Чи можна зупинити тестування?**
A: Поки що ні - дочекайтеся завершення або оновіть сторінку.

---

## Поради та рекомендації

### Для генерації якісних позицій:

1. **Використовуйте повний текст рішення**
   - Не тільки мотивувальну частину
   - Включайте контекст справи

2. **Додавайте коментарі**
   - Вказуйте на що звернути увагу
   - Що важливо виділити

3. **Експериментуйте з моделями**
   - Різні моделі - різні стилі
   - Claude - детальний аналіз
   - GPT - структурованість
   - Gemini - баланс

### Для ефективного пошуку:

1. **Спочатку згенеруйте позицію**
   - Пошук на основі позиції точніший
   - Ніж пошук за сирим текстом

2. **Перевіряйте топ-3 результати**
   - Найвищий score = найрелевантніше
   - Нижче 0.7 - можливо нерелевантно

### Для налаштування промптів:

1. **Змінюйте поступово**
   - Не змінюйте все одразу
   - Тестуйте кожну зміну

2. **Зберігайте резервні копії**
   - Скопіюйте промпти у файл
   - Перед великими змінами

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

### Для пакетного тестування:

1. **Почніть з малого**
   - Спочатку 5-10 рядків
   - Перевірте якість
   - Потім збільшуйте обсяг

2. **Налаштуйте паузу правильно**
   - Краще довше, ніж rate limit
   - Оптимально 1-2 секунди

3. **Зберігайте результати**
   - Одразу завантажуйте файл
   - Назва містить дату/час

---

## Технічна підтримка

Якщо виникли проблеми:

1. **Перезавантажте сторінку** - часто допомагає
2. **Перевірте API ключі** - чи налаштовані правильно
3. **Спробуйте іншу модель** - можливо проблема з конкретною
4. **Очистіть кеш браузера** - F12 → Application → Clear Storage

---

**Дякуємо за використання AI Асистента!** 🎉

Для додаткової інформації дивіться:
- [README.md](README.md) - технічна документація
- [BATCH_TESTING_README.md](BATCH_TESTING_README.md) - детально про пакетне тестування
- [PROMPT_EDITING.md](docs/PROMPT_EDITING.md) - глибоке занурення у промпти