README.md

---
title: Legal Position AI Analyzer
emoji: ⚖️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: "6.5.0"
app_file: app.py
pinned: false
license: mit
python_version: "3.11"
---

# ⚖️ AI Асистент для роботи з правовими позиціями Верховного Суду

Інтелектуальний інструмент для аналізу судових рішень та формування правових позицій Верховного Суду України з використанням AI.

## 🎯 Scope для поставки (LPD / Верховний Суд)

Поточний фокус замовника — **модернізація функціонала генерації правових позицій** (розділ «Генерація» + налаштування моделей/«роздумів» + поле коментаря).

- **In-scope (MVP):** генерація правових позицій + узгоджені налаштування моделей/Thinking/Comment.
- **Out-of-scope (якщо не прописано в ТЗ):** пошук і порівняльний аналіз можуть розглядатися як *опціональні* (і за потреби вимикаються у customer build).
- **Важливо про пошук:** якщо search/analysis увімкнено, індекси можуть завантажуватися з `DocSA/legal-position-indexes`, але це тестовий snapshot приблизно **1.5 роки давності** (може бути неактуальним).

Докладніше: [`docs/SCOPE_AND_DATA_FRESHNESS.md`](docs/SCOPE_AND_DATA_FRESHNESS.md)

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

### 💡 Генерація правових позицій
- Автоматичне формування проектів правових позицій з тексту судових рішень
- Підтримка різних форматів вводу: текст, URL, файл (.txt)
- Можливість додавання коментарів для уточнення контексту
- Автоматична класифікація за типом судочинства та категорією

### 🔍 Пошук схожих позицій *(опціонально)*
- Інтелектуальний пошук релевантних правових позицій у базі даних
- Пошук на основі згенерованої позиції або вхідного тексту
- Гібридний підхід: векторний пошук + BM25
- Відображення результатів з посиланнями на джерела
- Якщо customer build поставляється без retrieval-інфраструктури, цей модуль може бути вимкнений

### ⚖️ Порівняльний аналіз *(опціонально)*
- Детальний аналіз релевантності знайдених позицій
- Виявлення спільних правових аспектів
- Оцінка можливості застосування існуючих позицій
- Обґрунтовані висновки щодо необхідності створення нової позиції
- Не є критерієм приймання MVP, якщо це не зафіксовано окремо в ТЗ

### ⚙️ Редагування промптів
- Персональне налаштування промптів для AI
- Три типи промптів: системний, генерації, аналізу
- Повна ізоляція сесій між користувачами
- Безпечна робота на хмарних серверах

### 📊 **НОВЕ!** Пакетне тестування
- Масова генерація правових позицій з CSV файлів
- Підтримка всіх AI провайдерів
- Налаштування паузи між запитами (0-10 секунд)
- Збереження повних JSON результатів
- Прогрес-бар з відслідковуванням обробки
- Автоматичне збереження результатів з міткою часу

## 🎯 Підтримка AI провайдерів

### Для генерації:
- **OpenAI**: GPT-5.4, GPT-5.3 Chat Latest, GPT-5.2 (NEW! з reasoning), GPT-4o Mini Fine-Tuned (кастомні моделі)
- **Anthropic**: Claude Opus 4.6, Claude Sonnet 4.6 (з підтримкою Extended Thinking), Claude Haiku 4.5
- **Google**: Gemini 3 Flash, Gemini 3 Pro (з підтримкою Thinking Mode)
- **DeepSeek**: DeepSeek Chat

### Для аналізу:
- **OpenAI**: GPT-5.4, GPT-5.3 Chat Latest, GPT-5.2 (NEW! з reasoning)
- **Anthropic**: Claude Opus 4.6, Claude Sonnet 4.6 (з підтримкою Extended Thinking), Claude Haiku 4.5
- **Google**: Gemini 3 Flash, Gemini 3 Pro (з підтримкою Thinking Mode)
- **DeepSeek**: DeepSeek Chat

### 🆕 GPT-5.2 - Нова модель з reasoning!
- Покращене міркування для складних правових аналізів
- Контроль рівня reasoning: low/medium/high
- Налаштування деталізації відповідей
- Конфіденційність: опція не зберігати запити

📖 [Детальна документація GPT-5.2](docs/models/openai/GPT5_2_INTEGRATION.md) | [Швидкий старт](docs/models/openai/GPT5_2_QUICKSTART.md)

## 📋 Структура проекту

```
Legal_Position_2/
├── main.py                      # Головний файл додатку
├── interface.py                 # Gradio UI + інтеграція з сесіями
├── config.py                    # Конфігурація
├── prompts.py                   # Стандартні промпти
├── utils.py                     # Допоміжні функції
├── components.py                # Компоненти пошуку
│
├── src/
│   └── session/                 # Система управління сесіями
│       ├── state.py             # UserSessionState з custom_prompts
│       ├── manager.py           # SessionManager
│       └── storage.py           # Зберігання (Memory/Redis)
│
├── config/
│   └── environments/
│       └── default.yaml         # Налаштування
│
├── docs/
│   ├── PROMPT_EDITING.md        # Повна документація з промптів
│   └── QUICK_START_PROMPTS.md  # Швидкий старт
│
├── test_docs/                   # Тестові дані
│   └── df_lp_part_cd_test_29_result.csv
│
├── test_results/                # Результати пакетного тестування
│
├── HELP.md                      # Загальна допомога для користувачів (використовується інтерфейсом)
└── docs/                        # Документація (див. docs/README.md)
```

## 🛠️ Встановлення

### 1. Клонування репозиторію

```bash
git clone https://github.com/your-username/Legal_Position_2.git
cd Legal_Position_2
```

### 2. Встановлення залежностей

```bash
pip install -r requirements.txt
```

### 3. Налаштування змінних оточення

Створіть файл `.env` з необхідними API ключами:

```env
# AI Провайдери (хоча б один обов'язковий)
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
DEEPSEEK_API_KEY=your_deepseek_key

# AWS S3 (опціонально, для зберігання даних)
AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret

# Redis (опціонально, для production)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
```

### 4. Запуск додатку

Локальний запуск:

```bash
python app.py
```

Додаток буде доступний за адресою: `http://localhost:7860`

## 📖 Використання

### Базовий workflow

1. **Генерація правової позиції**
   - Відкрийте вкладку "💡 Генерація"
   - Оберіть провайдер AI та модель
   - Введіть текст судового рішення (або URL, або завантажте файл)
   - Додайте коментар (опціонально)
   - Натисніть "📝 Генерувати проект правової позиції"

2. **Пошук схожих позицій**
   - Перейдіть до вкладки "🔍 Пошук"
   - Оберіть тип пошуку:
     - На основі згенерованої позиції
     - На основі вхідного тексту
   - Перегляньте результати з посиланнями

3. **Аналіз релевантності**
   - Перейдіть до вкладки "⚖️ Аналіз"
   - Додайте уточнююче питання (опціонально)
   - Натисніть "⚖️ Аналіз результатів пошуку"
   - Отримайте детальний аналіз кожної знайденої позиції

4. **Редагування промптів**
   - Перейдіть до вкладки "⚙️ Налаштування"
   - Відредагуйте один або кілька промптів:
     - 📋 **Системний промпт** - роль AI
     - ⚖️ **Промпт генерації** - шаблон для створення позицій
     - 🔍 **Промпт аналізу** - шаблон для порівняння
   - Натисніть "💾 Зберегти промпти"
   - Повертайтесь до генерації - тепер використовуються ваші промпти!

**Важливо:** Промпти зберігаються тільки на час вашої сесії (30 хвилин без активності).

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

5. **Масова генерація правових позицій**
   - Перейдіть до вкладки "📊 Пакетне тестування"
   - Оберіть провайдер AI та модель
   - Налаштуйте паузу між запитами (рекомендовано 1-2 сек)
   - Завантажте CSV файл з колонкою `text`
   - Натисніть "📂 Завантажити CSV/XLSX файл" для перегляду
   - Запустіть тестування кнопкою "▶️ Запустити пакетне тестування"
   - Завантажте результати після завершення

**Формат результатів:** Повний JSON об'єкт з полями `title`, `text`, `proceeding`, `category`

Детальна інструкція: [docs/batch/BATCH_TESTING_README.md](docs/batch/BATCH_TESTING_README.md)

### 📖 Допомога

6. **Довідка по всьому функціоналу**
   - Перейдіть до вкладки "📖 Допомога"
   - Ознайомтесь з детальною документацією
   - Швидкий доступ до всіх можливостей додатку

## 🎨 Приклади налаштувань

### Приклад 1: Формальний стиль

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

### Приклад 2: Фокус на цивільних справах

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

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

<court_decision>
{court_decision_text}
</court_decision>
...
```

Більше прикладів: [docs/PROMPT_EDITING.md](docs/PROMPT_EDITING.md#приклади-використання)

## 🔒 Безпека та ізоляція сесій

### Гарантії безпеки

✅ **Ізоляція користувачів**
- Кожен користувач має унікальний session ID (UUID4)
- Дані зберігаються окремо для кожної сесії
- Неможливо отримати доступ до даних іншого користувача

✅ **Автоматична очистка**
- Сесії видаляються після 30 хвилин неактивності
- Background cleanup task запобігає витоку пам'яті

✅ **Thread-safe операції**
- Використання `asyncio.Lock` для конкурентного доступу
- Безпечна робота на багатокористувацьких серверах

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

```
Користувач 1 → Session ID: abc123 → {
    legal_position_json: {...}
    search_nodes: [...]
    custom_prompts: {
        'system': '...',
        'legal_position': '...',
        'analysis': '...'
    }
}

Користувач 2 → Session ID: def456 → {
    // Повністю ізольовані дані
}
```

## ⚙️ Конфігурація

### config/environments/default.yaml

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

# Налаштування пошуку
retriever:
  similarity_top_k: 10             # Кількість результатів
  bm25_top_k: 10

# Налаштування AI
llm:
  context_window: 128000
  chunk_size: 1024
```

### Production (Redis)

Для production використання рекомендується Redis:

```yaml
session:
  storage_type: "redis"

redis:
  host: "your-redis-host"
  port: 6379
  db: 0
  password: "your-password"
```

## 🚀 Deployment

### Deployment profiles

- **Customer MVP / handoff:** Generation + model/thinking/comment controls are the primary supported flow.
- **Optional modules:** Search and comparative analysis may be enabled only when retrieval indexes are available and accepted as in-scope.
- **Known limitation:** if retrieval uses `DocSA/legal-position-indexes`, that corpus is an older snapshot and may be stale.

### Hugging Face Spaces

1. Створіть новий Space на [Hugging Face](https://huggingface.co/spaces)
2. Оберіть SDK: Gradio
3. Завантажте код
4. Додайте secrets (API ключі) в Settings
5. Space автоматично запуститься

### Docker

```bash
docker build -t legal-position-ai .
docker run -p 7860:7860 --env-file .env legal-position-ai
```

### Local Server

```bash
# Development
python main.py

# Production
gunicorn main:app --workers 4 --bind 0.0.0.0:7860
```

## 📊 Технічні характеристики

### Підтримувані формати

- **Вхід**: Текст, URL (reyestr.court.gov.ua), TXT файли
- **Вихід**: JSON (структурована правова позиція)
- **Кодування**: UTF-8, CP1251

### Обмеження

- Максимальна довжина промпту: 50,000 символів
- Максимальна довжина тексту рішення: залежить від моделі (до 128K токенів)
- Час сесії: 30 хвилин без активності
- Максимум активних сесій: 1000 (налаштовується)

### Продуктивність

- Генерація позиції: 10-30 секунд (залежить від моделі)
- Пошук: 1-3 секунди
- Аналіз: 15-45 секунд (залежить від кількості результатів)

## 📚 Документація

- **[HELP.md](HELP.md)** - Загальна допомога для користувачів (доступна в додатку)
- **[docs/batch/BATCH_TESTING_README.md](docs/batch/BATCH_TESTING_README.md)** - Документація пакетного тестування
- **[PROMPT_EDITING.md](docs/PROMPT_EDITING.md)** - Повна технічна документація з редагування промптів
- **[QUICK_START_PROMPTS.md](docs/QUICK_START_PROMPTS.md)** - Швидкий старт для користувачів
- **[docs/changelog/CHANGES.md](docs/changelog/CHANGES.md)** - Детальний changelog

## 🔧 Troubleshooting

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

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

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

### Помилка при генерації

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

**Рішення:**
1. Перевірте наявність плейсхолдерів у промптах (`{court_decision_text}`, `{comment}`)
2. Спробуйте скинути промпти до стандартних
3. Перевірте API ключі

### Сесія закривається швидко

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

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

## 🤝 Внесок

Ваші внески вітаються! Будь ласка:

1. Fork репозиторій
2. Створіть feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit зміни (`git commit -m 'Add some AmazingFeature'`)
4. Push в branch (`git push origin feature/AmazingFeature`)
5. Відкрийте Pull Request

## 📝 Ліцензія

Цей проект ліцензований під [MIT License](LICENSE).

## 👥 Автори

- Розробка core функціоналу: [Your Name]
- Інтеграція session management та prompt editing: Claude Code (AI Assistant)
- Архітектура: аналіз та адаптація існуючого коду

## 🙏 Подяки

- [OpenAI](https://openai.com/) за GPT моделі
- [Anthropic](https://www.anthropic.com/) за Claude моделі
- [Google](https://ai.google.dev/) за Gemini моделі
- [DeepSeek](https://www.deepseek.com/) за DeepSeek моделі
- [LlamaIndex](https://www.llamaindex.ai/) за фреймворк для RAG
- [Gradio](https://www.gradio.app/) за інтерфейс

## 📞 Контакти

- GitHub Issues: [Create an issue](https://github.com/your-username/Legal_Position_2/issues)
- Email: your-email@example.com

---

**Версія:** 2.1 (з підтримкою пакетного тестування)

**Останнє оновлення:** 2026-01-03

**Статус:** 🟡 Handoff Candidate (generation-first MVP; optional retrieval modules require separate validation)