# Налаштування Perplexity API для веб-пошуку

## Чому Perplexity?

Perplexity API надає AI-моделі з **вбудованим веб-пошуком**, що дозволяє:

- ✅ Отримувати актуальну інформацію про бренди в реальному часі
- ✅ Виявляти конкурентів точніше (AI бачить їх згадки в інтернеті)
- ✅ Симулювати реальну поведінку AI-асистентів з доступом до інтернету
- ✅ Кращі результати для Brand Awareness та Scanner

## Отримання API ключа

### 1. Зареєструйтеся на Perplexity

Відкрийте: https://www.perplexity.ai/settings/api

Або:
1. Перейдіть на https://www.perplexity.ai
2. Натисніть на профіль (правий верхній кут)
3. Settings → API

### 2. Створіть API ключ

1. Натисніть **"Generate API Key"**
2. Скопіюйте ключ (формат: `pplx-xxxxxxxxxxxxx`)
3. **Важливо:** збережіть ключ в безпечному місці — він показується тільки один раз

### 3. Додайте кредити

Perplexity працює на prepaid основі:
- Мінімальне поповнення: $10-20
- Модель `sonar`: $1.00 input + $1.00 output per 1M tokens
- Один аналіз (~10-15 запитів): ~$0.02-0.05

Додати кредити: https://www.perplexity.ai/settings/billing

## Налаштування проєкту

### 1. Відкрийте `.env` файл

```bash
# У кореневій папці проєкту
e:\AI Visibility Snapshot\.env
```

### 2. Оновіть SCANNER конфігурацію

Замініть існуючі рядки SCANNER на:

```env
SCANNER_PROVIDER=perplexity
SCANNER_MODEL=sonar
SCANNER_BASE_URL=https://api.perplexity.ai
SCANNER_API_KEY=pplx-ваш-ключ-тут
SCANNER_TEMPERATURE=0.4
```

### 3. Перезапустіть Streamlit

```bash
streamlit run app.py
```

## Моделі Perplexity

| Модель | Input/1M | Output/1M | Рекомендація |
|--------|----------|-----------|--------------|
| **sonar** | $1.00 | $1.00 | ✅ Рекомендовано для Scanner |
| sonar-pro | $3.00 | $15.00 | Для складних досліджень |

**Для нашого випадку `sonar` достатньо** — він швидкий, дешевий і має повний веб-пошук.

## Перевірка роботи

Після налаштування запустіть аналіз будь-якого сайту. Ви побачите:

### Scanner буде використовувати веб-пошук:
- Більш актуальні згадки брендів
- Краще виявлення конкурентів
- Реалістичні AI-рекомендації

### Brand Awareness покаже:
- Чи бренд присутній в веб-пошуку (а не тільки в навчальних даних)
- Актуальну інформацію про конкурентів

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

### Q: Чи потрібен веб-пошук для всіх ролей?

**A:** Ні. Рекомендована конфігурація:
- **GENERATION** (генерація запитів): Local LM Studio (без інтернету) ✅
- **SCANNER** (перевірка AI-видимості): Perplexity з веб-пошуком ✅
- **ANALYSIS** (аналіз результатів): Local LM Studio (без інтернету) ✅

Тільки Scanner потребує веб-доступу для реалістичної симуляції AI-рекомендацій.

### Q: Скільки коштує один аналіз?

**A:** З Perplexity `sonar`:
- Brand Awareness (1 запит): ~$0.002
- Scanner (10 запитів): ~$0.02-0.03
- Gap Analysis (1 запит): ~$0.003
- **Загалом: ~$0.03-0.05 за повний аналіз**

### Q: Чи можна використовувати безкоштовну альтернативу?

**A:** OpenAI без веб-пошуку (`gpt-5-mini`) працює, але:
- ❌ Показує тільки знання з навчальних даних (~середина 2025)
- ❌ Не бачить нові бренди
- ❌ Менш точне виявлення конкурентів

Для продакшн-використання рекомендуємо Perplexity.

## Troubleshooting

### Помилка: "Invalid API key"

Перевірте:
1. Ключ скопійовано повністю (починається з `pplx-`)
2. У `.env` файлі немає зайвих пробілів
3. Ключ активний на https://www.perplexity.ai/settings/api

### Помилка: "Insufficient credits"

Додайте кредити: https://www.perplexity.ai/settings/billing

### Модель не підтримує temperature

Perplexity API іноді обмежує `temperature` для `sonar`. Код автоматично обробляє цю помилку (fallback без temperature).

## Підтримка

Документація Perplexity API: https://docs.perplexity.ai

Наша документація: `docs/business-model-flow.md`