docs/API.md

# API Документация

## Обзор

SEO AI Editor предоставляет REST API для анализа текстов. API построен на FastAPI и автоматически генерирует интерактивную документацию.

## Базовый URL

```
http://127.0.0.1:8001
```

## Endpoints

### GET `/`

Возвращает главную страницу приложения (HTML).

**Ответ:** HTML страница с интерфейсом

---

### POST `/analyze`

Выполняет комплексный анализ текста с использованием N-грамм, BM25 и BERT.

#### Запрос

**Content-Type:** `application/json`

**Тело запроса:**

```json
{
  "target_text": "string (обязательно)",
  "competitors": ["string"] (обязательно, может быть пустым массивом),
  "keywords": ["string"] (обязательно, может быть пустым массивом),
  "language": "string" (опционально, по умолчанию "en")
}
```

**Параметры:**

| Параметр | Тип | Обязательный | Описание |
|----------|-----|--------------|----------|
| `target_text` | string | Да | Текст пользователя для анализа |
| `competitors` | array[string] | Да | Массив текстов конкурентов |
| `keywords` | array[string] | Да | Массив ключевых фраз (каждая фраза - отдельный элемент) |
| `language` | string | Нет | Код языка: `en`, `ru`, `de`, `es`, `it` |

#### Ответ

**Статус:** 200 OK

**Content-Type:** `application/json`

```json
{
  "ngram_stats": {
    "unigrams": [
      {
        "ngram": "string",
        "target_count": 0,
        "competitor_avg": 0.0
      }
    ],
    "bigrams": [...],
    "trigrams": [...],
    "quadgrams": [...]
  },
  "bm25_recommendations": [
    {
      "word": "string",
      "type": "1-gram" | "2-gram" | "3-gram",
      "my_score": 0.0,
      "avg_comp_score": 0.0,
      "action": "ok" | "add" | "remove",
      "count": 0
    }
  ],
  "bert_analysis": {
    "global_scores": [
      {
        "name": "string",
        "score": 0.0,
        "is_me": true
      }
    ],
    "detailed": [
      {
        "phrase": "string",
        "my_max_score": 0.0,
        "comp_max_score": 0.0,
        "status": "ok" | "good" | "warning" | "bad",
        "recommendation": "string",
        "my_top_chunks": [
          {
            "text": "string",
            "score": 0.0
          }
        ],
        "comp_top_chunks": [
          {
            "text": "string",
            "score": 0.0,
            "source": "string"
          }
        ]
      }
    ]
  }
}
```

#### Структура ответа

##### ngram_stats

Статистика по N-граммам (1-4 слова).

**Поля:**
- `ngram` - текст N-граммы (лемматизированный)
- `target_count` - количество вхождений в целевом тексте
- `competitor_avg` - среднее количество вхождений у конкурентов

**Сортировка:** По максимальному значению (target_count или competitor_avg)

##### bm25_recommendations

Рекомендации по оптимизации частоты слов/фраз с использованием алгоритма BM25.

**Особенности алгоритма:**
- **Полная декомпозиция фраз**: Каждая ключевая фраза автоматически разбивается на все возможные под-н-граммы длиной от 1 до 3 слов
  - Пример: фраза "chicken road casino" анализируется как:
    - Униграммы: "chicken", "road", "casino"
    - Биграммы: "chicken road", "road casino"
    - Триграммы: "chicken road casino"
  - Это позволяет находить не только точные совпадения, но и частичные вхождения ключевых фраз
  - Дубликаты автоматически удаляются

**Поля:**
- `word` - слово или фраза (лемматизированная)
- `type` - тип: "1-gram", "2-gram", "3-gram"
- `my_score` - BM25 score в целевом тексте
- `avg_comp_score` - средний BM25 score у конкурентов
- `action` - рекомендуемое действие:
  - `"ok"` - частота в норме
  - `"add"` - нужно добавить (ваш score ниже среднего конкурентов)
  - `"remove"` - нужно убрать (ваш score значительно выше среднего конкурентов)
- `count` - рекомендуемое количество добавлений/удалений (рассчитывается на основе разницы скоров)

**Пороги для действий:**
- Униграммы: порог 0.5
- Биграммы: порог 0.25
- Триграммы: порог 0.15

**Сортировка:** 
1. Сначала проблемные рекомендации (add/remove)
2. Затем по длине фразы (длинные фразы важнее)
3. Затем алфавитно

##### bert_analysis

Семантический анализ с использованием BERT.

**global_scores:**
- `name` - название текста ("Мой текст" или "Конкурент #N")
- `score` - средний максимальный score по всем ключевым фразам (0.0 - 1.0)
- `is_me` - флаг, является ли это целевым текстом

**detailed:**
Для каждой ключевой фразы:
- `phrase` - исходная ключевая фраза
- `my_max_score` - максимальный score в целевом тексте (0.0 - 1.0)
- `comp_max_score` - максимальный score у конкурентов
- `status` - статус:
  - `"good"` - score >= 0.7
  - `"ok"` - 0.5 <= score < 0.7
  - `"warning"` - score < 0.5 или конкуренты лучше на 0.1+
  - `"bad"` - score < 0.5
- `recommendation` - текстовое описание рекомендации
- `my_top_chunks` - топ-5 наиболее релевантных предложений из целевого текста
- `comp_top_chunks` - топ-5 наиболее релевантных предложений у конкурентов (с указанием источника)

#### Примеры запросов

**cURL:**
```bash
curl -X POST "http://127.0.0.1:8001/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "target_text": "Это мой текст для анализа SEO.",
    "competitors": ["Текст конкурента номер один.", "Текст конкурента номер два."],
    "keywords": ["SEO анализ", "текст"],
    "language": "ru"
  }'
```

**Python:**
```python
import requests

response = requests.post(
    "http://127.0.0.1:8001/analyze",
    json={
        "target_text": "Это мой текст для анализа SEO.",
        "competitors": ["Текст конкурента номер один.", "Текст конкурента номер два."],
        "keywords": ["SEO анализ", "текст"],
        "language": "ru"
    }
)

data = response.json()
print(data)
```

**JavaScript:**
```javascript
fetch('http://127.0.0.1:8001/analyze', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    target_text: "Это мой текст для анализа SEO.",
    competitors: ["Текст конкурента номер один.", "Текст конкурента номер два."],
    keywords: ["SEO анализ", "текст"],
    language: "ru"
  })
})
.then(response => response.json())
.then(data => console.log(data));
```

#### Ошибки

**400 Bad Request**
Неверный формат запроса или отсутствуют обязательные поля.

**422 Unprocessable Entity**
Ошибка валидации данных (например, неверный код языка).

**500 Internal Server Error**
Внутренняя ошибка сервера (проблемы с моделями, памятью и т.д.).

## Интерактивная документация

После запуска приложения доступны:

- **Swagger UI**: `http://127.0.0.1:8001/docs`
- **ReDoc**: `http://127.0.0.1:8001/redoc`

Эти интерфейсы позволяют:
- Просматривать все endpoints
- Тестировать API прямо в браузере
- Видеть схемы данных
- Просматривать примеры запросов и ответов