docs/SCOPE_AND_DATA_FRESHNESS.md

# Scope, data freshness & expectations (LPD / Верховний Суд)

Цей документ фіксує **межі поставки (scope)** та **очікування щодо даних**, щоб уникнути непорозумінь при передачі коду замовнику.

## 1) In-scope (обов’язково для MVP)

### 1.1 Генерація правових позицій
- Вкладка/розділ: **«Генерація правових позицій»**.
- Вхід: текст / URL / файл.
- Вихід: **структурований JSON** з полями: `title`, `text`, `proceeding`, `category`.

### 1.2 Налаштування моделей і режимів «роздумів»
Для розділу генерації мають бути узгоджені (з порталом) параметри:
- `provider` (openai | anthropic | gemini | deepseek)
- `model`
- `thinking_enabled` (true/false)
- `thinking_level` (low | medium | high) — **уніфікований** рівень; деталізація/мапінг до провайдерів робиться в backend.
- (опційно) `openai_verbosity` (low | medium | high) — якщо замовник хоче це в UI.

### 1.3 Додаткове поле «Коментар» (опціонально)
- UI: textarea **«Коментар до генерації (опціонально)»**.
- Backend payload: `comment`.
- Призначення: дати моделі коротку інструкцію/акцент (що підкреслити, який аспект важливий тощо).

## 2) Out-of-scope (не є критерієм приймання MVP, якщо не зазначено в ТЗ)

### 2.1 Пошук схожих позицій
Функціонал пошуку (vector+BM25) може бути:
- залишений у коді як **опціональний**, або
- **вимкнений у customer build**, якщо замовнику зараз не потрібен.

### 2.2 Порівняльний аналіз / прецедентний аналіз
Аналіз результатів пошуку також вважається **опціональним**, якщо він не прописаний у ТЗ.

## 3) Джерело індексів (search KB) та актуальність даних

Якщо пошук увімкнений, застосунок може завантажувати індекси з HuggingFace Dataset:
- `https://huggingface.co/datasets/DocSA/legal-position-indexes`

### Важливий нюанс
- Ця база індексів була отримана **приблизно 1.5 роки тому** як тестовий snapshot від ВС.
- З того часу вона **не оновлювалася**.

### Наслідки
- Пошук/аналіз може **не знаходити** нові/оновлені позиції після дати snapshot.
- Це **не дефект генерації**; це обмеження актуальності корпусу для retrieval-компоненти.

### Як комунікуємо замовнику
- У документації та Help UI має бути явна примітка: **search/analysis optional + data snapshot may be outdated**.
- За потреби — показувати користувачу `Index snapshot: …` (якщо буде додано manifest/version).

## 4) Якщо замовнику колись знадобиться актуалізація
Це окремий потік робіт (не обов’язково для MVP):
- хто надає нові дані (ВС / відповідальна сторона)
- хто будує індекси
- де вони зберігаються
- частота оновлень (разово / періодично)