README.md

metadata

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.

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

💡 Генерація правових позицій

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

🔍 Пошук схожих позицій

• Інтелектуальний пошук релевантних правових позицій у базі даних
• Пошук на основі згенерованої позиції або вхідного тексту
• Гібридний підхід: векторний пошук + BM25
• Відображення результатів з посиланнями на джерела

⚖️ Порівняльний аналіз

• Детальний аналіз релевантності знайдених позицій
• Виявлення спільних правових аспектів
• Оцінка можливості застосування існуючих позицій
• Обґрунтовані висновки щодо необхідності створення нової позиції

⚙️ Редагування промптів

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

📊 НОВЕ! Пакетне тестування

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

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

Для генерації:

• OpenAI: GPT-5.2 (NEW! з reasoning), GPT-4.1, GPT-4o, custom fine-tuned models
• Anthropic: Claude 4.5 Sonnet (з підтримкою Extended Thinking)
• Google: Gemini 3.0 Flash, 3.5 Flash (з підтримкою Thinking Mode)
• DeepSeek: DeepSeek Chat

Для аналізу:

• OpenAI: GPT-5.2 (NEW! з reasoning), GPT-4.1, GPT-4o
• Anthropic: Claude 4.5 Sonnet
• Google: Gemini 3.0 Flash, 3.5 Flash
• DeepSeek: DeepSeek Chat

🆕 GPT-5.2 - Нова модель з reasoning!

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

📖 Детальна документація GPT-5.2 | Швидкий старт

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

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/                # Результати пакетного тестування
│
├── BATCH_TESTING_README.md      # Документація пакетного тестування
├── HELP.md                      # Загальна допомога для користувачів
└── CHANGES.md                   # Детальний changelog

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

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

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

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

pip install -r requirements.txt

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

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

# 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. Запуск додатку

python main.py

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

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

Базовий workflow

1. Генерація правової позиції

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

2. Пошук схожих позицій

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

3. Аналіз релевантності

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

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

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

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

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

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

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

Детальна інструкція: BATCH_TESTING_README.md

📖 Допомога

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

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

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

Системний промпт:

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

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

Промпт генерації:

Дотримуйся цих інструкцій.

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

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

Більше прикладів: 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

# Налаштування сесій
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:

session:
  storage_type: "redis"

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

🚀 Deployment

Hugging Face Spaces

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

Docker

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

Local Server

# 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 - Загальна допомога для користувачів (доступна в додатку)
• BATCH_TESTING_README.md - Документація пакетного тестування
• PROMPT_EDITING.md - Повна технічна документація з редагування промптів
• QUICK_START_PROMPTS.md - Швидкий старт для користувачів
• CHANGES.md - Детальний changelog версії 2.0

🔧 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.

👥 Автори

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

🙏 Подяки

• OpenAI за GPT моделі
• Anthropic за Claude моделі
• Google за Gemini моделі
• DeepSeek за DeepSeek моделі
• LlamaIndex за фреймворк для RAG
• Gradio за інтерфейс

📞 Контакти

• GitHub Issues: Create an issue
• Email: your-email@example.com

---

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

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

Статус: ✅ Production Ready