README.md

---
title: "NPA_AI_Analysis_Assistant v.3.0"
emoji: "🛡️"
colorFrom: "blue"
colorTo: "green"
sdk: "gradio"
sdk_version: "5.8.0"
app_file: app.py
pinned: false
---

# NPA Analysis Assistant v.3.0

## Призначення

AI Асистент аналізу нормативно-правових актів (НПА) - це професійний інструмент, призначений для автоматизації процесу антикорупційної експертизи проектів нормативно-правових актів. Використовуючи потужні моделі штучного інтелекту, система допомагає виявляти потенційні корупціогенні фактори відповідно до офіційної методології НАЗК.

## Ключові особливості

- **Мультипровайдерна підтримка**: використання моделей від OpenRouter і Anthropic
- **Розширений вибір моделей**: підтримка різних моделей великої мовної моделі (LLM)
- **Режим роздумів**: покрокове мислення для моделей Anthropic Claude
- **Адаптивний інтерфейс**: автоматична зміна доступних опцій залежно від обраного провайдера
- **Україномовний аналіз**: повна підтримка української мови на всіх етапах
- **Професійний експертний висновок**: структурований текст з рекомендаціями

## Технічні вимоги

### Залежності
- Python 3.8+
- Anthropic SDK (v0.47.1+)
- OpenAI SDK (v1.0.0+)
- Gradio (v4.44.1+)
- python-dotenv (v1.0.0+)
- requests

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

```bash
# Клонування репозиторію
git clone https://github.com/SZabolotnii/NPA_Analysis_Assistant.git
cd NPA_Analysis_Assistant

# Створення віртуального середовища
python -m venv npa_env
source npa_env/bin/activate  # На Windows: npa_env\Scripts\activate

# Встановлення залежностей
pip install -r requirements.txt
```

## Налаштування API ключів

Для роботи системи необхідно мати API ключі для провайдерів, які ви плануєте використовувати:

### OpenRouter (рекомендовано)
1. Зареєструйтесь на [OpenRouter](https://openrouter.ai/)
2. Отримайте API ключ у вашому профілі
3. Експортуйте змінну середовища:
```bash
export OPENROUTER_API_KEY=ваш-api-ключ
```

### Anthropic (опціонально)
1. Зареєструйтесь на [Anthropic](https://www.anthropic.com/)
2. Отримайте API ключ для Claude
3. Експортуйте змінну середовища:
```bash
export ANTHROPIC_API_KEY=ваш-api-ключ
```

## Запуск системи

```bash
# Запуск локальної версії
python app.py

# Запуск з публічним доступом через Gradio
python main.py
```

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

### 1. Основний інтерфейс

- **Поле введення тексту НПА**: Вставте текст нормативно-правового акту для аналізу.
- **Вибір провайдера**: Оберіть провайдера LLM (OpenRouter або Anthropic).
- **Вибір моделі**: Оберіть конкретну модель для аналізу в межах обраного провайдера.
- **Режим роздумів**: Увімкніть для більш глибокого аналізу (доступно тільки для моделей Anthropic).
- **Бюджет токенів для роздумів**: Налаштуйте обсяг роздумів (від 1024 до 8000 токенів).

### 2. Процес аналізу

1. **Підготовка**: Вставте повний текст проекту НПА в текстове поле.
2. **Налаштування**: Оберіть провайдера та модель для аналізу.
3. **Додаткові параметри**: За бажанням увімкніть режим роздумів (якщо підтримується).
4. **Запуск**: Натисніть кнопку "Аналіз".
5. **Результат**: Перегляньте висновок на вкладці "Висновок".
6. **Роздуми моделі**: Якщо було увімкнено режим роздумів, перегляньте процес міркування на вкладці "Роздуми моделі".

### 3. Вибір провайдера та моделі

#### OpenRouter (за замовчуванням)
- **openrouter/quasar-alpha**: Потужна модель з широким контекстним вікном.
- Інші моделі: google/gemini-2.0-flash-thinking-exp:free, deepseek/deepseek-r1-zero:free, тощо.

#### Anthropic
- **claude-3-7-sonnet-latest**: Рекомендована потужна модель для детального аналізу і можливим режимом роздумів.
- **claude-3-5-haiku-latest**: Більш проста, швидша та дешевша модель.

### 4. Режим роздумів

Режим роздумів дозволяє моделі проводити покрокове міркування перед наданням висновку. Цей режим:
- Доступний тільки для провайдера Anthropic
- Значно покращує якість аналізу
- Займає більше часу та ресурсів
- Автоматично відображає хід роздумів на відповідній вкладці

### 5. Інтерпретація результатів

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

## Усунення проблем

| Проблема | Можливе рішення |
|----------|------------------|
| Помилка "API ключ не знайдено" | Перевірте, чи правильно експортовано змінні середовища |
| Таймаут при аналізі | Зменшіть розмір тексту або бюджет токенів для роздумів |
| Пуста або неповна відповідь | Спробуйте іншу модель або провайдера |
| Помилка "NoneType object" | Перевірте підключення до інтернету та правильність API ключа |
| Низька якість аналізу | Увімкніть режим роздумів та збільште бюджет токенів |

## Обмеження

- Аналіз дуже великих документів може бути обмежений контекстним вікном моделі
- Безкоштовні моделі можуть мати нижчу якість аналізу
- Режим роздумів доступний лише для моделей Anthropic


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

За питаннями та пропозиціями звертайтеся: [email protected]

---

## Технічна інформація для розробників

### Архітектура системи

Система побудована на модульній архітектурі:
- **app.py** / **main.py**: Точки входу для запуску системи
- **src/analyzer.py**: Основний модуль для аналізу НПА
- **src/llm_providers.py**: Абстракція різних LLM провайдерів
- **src/interface.py**: Gradio інтерфейс користувача
- **src/prompts.py**: Шаблони промптів для аналізу

### Розширення підтримуваних провайдерів

Для додавання нового провайдера потрібно:
1. Створити новий клас, що наслідує `LLMProvider` в `llm_providers.py`
2. Реалізувати всі абстрактні методи
3. Додати новий провайдер у функцію `get_provider()`
4. Оновити `get_available_providers()`

## Ліцензія
MIT License