# SEO AI Editor — исчерпывающая документация функционала, логики и алгоритмики

Документ описывает приложение как инженерную спецификацию: что делает каждый модуль, какие данные принимает и возвращает, какие формулы использует, какие ограничения применяет и как воспроизвести поведение системы без чтения исходного кода.

---

## 1) Концепция приложения

`SEO AI Editor` объединяет два аналитических контура и один контур улучшения текста:

1. **SEO-контур** (`POST /analyze`)
   - Word Count (total/significant)
   - N-gram анализ (1..4)
   - BM25-рекомендации (`add/remove/ok`)
   - BERT-семантика по ключам
   - Title-анализ (length/ngrams/coverage/BERT)

2. **Semantic Core** (`POST /api/v1/semantic/analyze`, `POST /api/v1/semantic/search`)
   - NLP-разбор и лемматизация
   - семантический граф (слова + фразы)
   - веса узлов и связей в шкале `1..100`
   - гипертекстовая разметка
   - реферат
   - смысловой поиск по словам и фразам
   - сравнение с конкурентами (включая таблицу мощных терминов)

3. **LLM Optimizer** (`POST /api/v1/optimizer/run`)
   - итеративная локальная оптимизация текста
   - многокритериальный скоринг с защитой от деградации
   - каскад уровней правок (от минимальных к более широким)
   - детализированный debug-лог по кандидатам

---

## 2) Архитектура и ответственность файлов

- `app.py` — FastAPI оркестратор, endpoint-ы, связывание модулей.
- `models.py` — Pydantic-модели входов/выходов.
- `logic.py` — SEO-ядро: токены, n-grams, BM25, BERT, Title.
- `nlp_processor.py` — NLP-предобработка для semantic-контура.
- `semantic_graph.py` — построение графа и вычисление смысловых весов.
- `highlighter.py` — разметка текста по semantic-весам.
- `summarizer.py` — генерация реферата.
- `search.py` — смысловой поиск в графе (фразы + слова).
- `url_fetcher.py` — извлечение текста/title из URL с выбором user-agent.
- `optimizer.py` — LLM-оптимизация с обратной связью от метрик.
- `templates/index.html` — frontend (UI + клиентская логика JS).

---

## 3) Поддерживаемые языки

Поддерживаемые языки анализа:
- `ru`, `en`, `de`, `es`, `it`, `pl`, `pt`

Языки задаются кодом и сопоставляются с spaCy-моделями в `logic.py` (`MODEL_NAMES`).

---

## 4) Backend API и контракты

## 4.1 `POST /analyze`

### Назначение
Комплексный SEO-анализ target-текста относительно конкурентов и ключевых фраз.

### Вход (`AnalysisRequest`)
- `target_text: str`
- `competitors: List[str]`
- `keywords: List[str]`
- `language: str`
- `target_title: str`
- `competitor_titles: List[str]`

### Выход (`AnalysisResponse`)
- `ngram_stats`
- `bm25_recommendations`
- `bert_analysis`
- `word_counts`
- `title_analysis`

### Оркестрация в `app.py`
1. Word counts (`count_words`) для target и каждого competitor.
2. N-gram статистика (`calculate_ngram_stats`).
3. Нормализация ключей (`parse_keywords`) и BM25 (`calculate_bm25_recommendations`).
4. BERT-анализ (`perform_bert_analysis`).
5. Title-анализ (`analyze_title`) если `target_title` не пустой.

---

## 4.2 `POST /api/v1/semantic/analyze`

### Назначение
Построение semantic-среза по target и конкурентам.

### Вход (`SemanticAnalyzeRequest`)
- `text: str`
- `competitors: List[str]`
- `language: str`
- `threshold: int` (порог подсветки)
- `compression_ratio: float` (доля предложений в реферате)

### Выход (`SemanticAnalyzeResponse`)
- `target`:
  - `graph` (`nodes`, `links`)
  - `markup_text`
  - `summary`
  - `top_keywords`
  - `word_weights`
  - `stats`
- `competitors[]`: тот же формат
- `comparison`:
  - `target_nodes`, `target_links`
  - `avg_comp_nodes`, `avg_comp_links`
  - `num_competitors`
  - `term_power_table`

### Логика таблицы `term_power_table`
Для каждого термина из объединения target + competitors:
- `target_weight`
- `competitor_avg_weight`
- `competitor_weights` (`K1..Kn`)
- `comp_occurrence` (`X` в `X/Y`)
- `comp_total` (`Y`)
- `term_type` (`word` или `phrase`)

---

## 4.3 `POST /api/v1/semantic/search`

### Назначение
Смысловой поиск по документу через граф.

### Вход (`SemanticSearchRequest`)
- `query_text`
- `text`
- `language`
- `top_n`

### Выход (`SemanticSearchResponse`)
- `results[]`: `lemma`, `score (1..100)`, `type (word|phrase)`

---

## 4.4 URL Import API

### `GET /api/v1/url/user-agents`
Возвращает список пресетов user-agent для выбора в UI.

### `POST /api/v1/url/fetch`
Извлекает `title` и основной `text` страницы:
- вход: `url`, `user_agent`, `timeout_seconds`
- выход: `ok`, `status_code`, `title`, `text`, `error`, `final_url`, agent-метаданные.

Обработка ошибок не ломает UI: endpoint возвращает `ok=false` и `error`.

---

## 4.5 `POST /api/v1/optimizer/run`

### Назначение
Итеративная локальная дооптимизация target-текста через LLM.

### Вход (`OptimizerRequest`)
- аналитические данные: `target_text`, `competitors`, `keywords`, `language`, `target_title`, `competitor_titles`
- LLM: `api_key`, `api_base_url`, `model`, `temperature`
- стратегия: `max_iterations`, `candidates_per_iteration`, `optimization_mode`

### Выход (`OptimizerResponse`)
- `optimized_text`
- `baseline_metrics`, `final_metrics`
- `iterations[]` (подробный лог шагов)
- `applied_changes`
- `optimization_mode`
- `error` (если есть)

---

## 5) Подробная алгоритмика по модулям

## 5.1 `logic.py` — SEO-ядро

### `load_model_if_missing(lang)`
Ленивая загрузка spaCy-модели конкретного языка. Цель: не загружать все модели на старте (критично для HF ресурсов).

### `load_models()`
Служебная массовая загрузка моделей (используется ограниченно; основной путь в проде — lazy).

### `get_doc(text, lang)`
Единая точка получения spaCy `Doc` с предобработкой языка/модели.

### `is_valid_token(t)`
Фильтр значимых токенов (исключает шумовые категории: punctuation/space/часть stop и др.).

### `get_lemmas_flat(text, lang)`
Плоский список лемм значимых токенов. Базовый строительный блок для метрик.

### `generate_ngrams_safe(text, lang, n)` — Smart Window
Ключевой принцип:
- размер окна задается по **значимым** словам;
- stop-слова внутри валидного окна могут сохраняться для естественных фраз;
- символные границы (punct/num/sym) не дают сшивать ложные фразы.

Это гарантирует более естественные n-grams и согласованность между разными подсистемами.

### `count_words(text, lang)`
Возвращает:
- `total` — количество словоформ
- `significant` — количество значимых токенов после фильтра

### `calculate_ngram_stats(target_text, competitor_texts, lang)`
Строит частотные словари 1..4-грамм, агрегирует:
- частоты target
- средние частоты competitors
- сигналы дефицита/избытка
- детализацию по каждому конкуренту (для интерфейсных таблиц)

### `parse_keywords(raw_phrases, lang)`
Нормализует сырые ключи пользователя в:
- фразовые ключи
- униграммы
с учетом текущего языка и лемматизации.

### `calculate_bm25_recommendations(...)` — Mirror Principle
BM25 использует тот же подход токенизации/фразогенерации, что и n-gram ядро.
Смысл:
- сравнить релевантность target и среднего competitor-профиля по тем же термам;
- выдать действие:
  - `add` — недобор терма,
  - `remove` — вероятный переспам,
  - `ok` — баланс.

### `get_bert_model()`
Ленивая инициализация sentence-transformers модели.

### `perform_bert_analysis(target_text, competitor_texts, key_phrases, lang)`
Для каждой ключевой фразы:
- ищет наиболее близкие чанки текста;
- считает similarity для target и competitors;
- формирует детализацию (`my_max_score`, competitor-сравнение, статусы).

### `analyze_title(target_title, competitor_titles, raw_keywords, lang)`
Оркестратор Title-пайплайна:
- `_title_length`
- `_title_ngrams`
- `_title_keyword_coverage`
- `_title_bert`

#### `_title_length(...)`
Сравнивает длину target title с конкурентным диапазоном/средним.

#### `_title_ngrams(...)`
N-gram сопоставление title-уровня.

#### `_title_keyword_coverage(...)`
Проверяет покрытие пользовательских ключей в target и competitor title.

#### `_title_bert(...)`
Оценивает semantic-близость title к ключевому набору.

---

## 5.2 `nlp_processor.py`

### `preprocess_text(text, lang)`
Преобразует текст в структуру предложений:
- `raw_text`
- `tokens[]` с полями `text`, `whitespace`, `lemma`, `is_significant`, `is_punct`, `is_space`
- `lemmas_clean` (очищенный список лемм)

Критично: сохранение `whitespace` и исходных токенов позволяет восстановить текст UI-послойно без потери форматирования.

---

## 5.3 `semantic_graph.py` — математическое ядро

### `_normalize_to_1_100(values)`
Нормализация произвольных весов в целочисленную шкалу `1..100`.

### `_extract_significant_lemmas(sent)`
Достает значимые леммы из предложения.

### `_is_noise_sentence(text)`
Отбрасывает шумовые фрагменты (короткие CTA, boilerplate-паттерны).

### `_canonicalize_term(term)`
Rule-based каноникализация термов (снижение дублей и вариативности).

### `_extract_phrase_candidates(sentence_text, lang)`
Извлечение кандидатных фраз через `generate_ngrams_safe` и фильтры.

### `_normalize_lemma_sequence(lemmas)`
Нормализация последовательностей лемм для устранения артефактов.

### `build_semantic_graph(sentences_data, lang)`
Базовые шаги:
1. Сформировать множество терминов (слова + фразы).
2. Подсчитать частоты терминов и совместные появления.
3. Построить направленный граф.
4. Рассчитать вес ребра:
   - `P(B|A) = cooc(A,B) / occ(A) * 100`
   - затем ограничение в `0..100`.
5. Рассчитать важность узлов:
   - PageRank как глобальная связность,
   - termness/coverage корректировки,
   - штрафы для слишком общих доменных токенов.
6. Вернуть граф и карту `word_weights`.

### `get_graph_data_for_frontend(graph, top_edges_per_node=8)`
Сериализует `networkx` граф в плоский JSON:
- `nodes[]`
- `links[]`
с ограничением числа ребер на узел для управляемого рендера.

### `get_top_keywords(node_weights, top_n=20)`
Возвращает top-N терминов по весу.

---

## 5.4 `highlighter.py`

### `generate_markup_for_frontend(sentences_data, word_weights, threshold=50)`
Маркирует важные блоки:
- если вес леммы/фразы >= порога, блок становится `is_link=true`;
- соседние значимые токены могут объединяться в один кликабельный сегмент;
- возвращается структура, удобная для реактивного рендера в UI.

---

## 5.5 `summarizer.py`

### `generate_summary(sentences_data, word_weights, compression_ratio)`
Скоринг предложения:
- `score = sum(weight(unique_lemmas)) / sqrt(token_count)`

Далее:
1. сортировка по score убыв.
2. выбор top по `compression_ratio`
3. восстановление хронологического порядка для читабельности.

---

## 5.6 `search.py`

### `_normalize_query_text(text)`
Нормализует запрос для устойчивого поиска.

### `semantic_search(query_text, G, word_weights, language, top_n)`
Алгоритм:
1. Нормализовать и лемматизировать запрос.
2. Приоритетно проверить фразы (tri/bi) из запроса.
3. Fallback на слова.
4. Для найденных точек входа добавить соседей по графу.
5. Собрать score из силы связи и веса узла.
6. Нормализовать score в `1..100`.
7. Вернуть top-N и тип (`phrase`/`word`).

---

## 5.7 `url_fetcher.py`

### `get_user_agent_presets()`
Возвращает список пресетов (Googlebot, Bingbot, ChatGPT user-agent, GPTBot, Chrome Desktop и др.).

### `_normalize_whitespace(text)`
Схлопывает лишние пробелы/переводы строк.

### `_normalize_url(url)`
Приводит URL к валидному виду (схема, trimming).

### `_resolve_user_agent(user_agent_key)`
По ключу выбирает фактическую строку user-agent.

### `_extract_main_text_and_title(html)`
HTML extraction pipeline:
- удалить `script/style/noscript/nav/footer/header/form/svg` и прочий boilerplate;
- приоритетно извлекать `article/main`;
- fallback на абзацы/списки;
- final fallback на `body` текст;
- вернуть очищенный `title` и основной `text`.

### `fetch_url_content(url, user_agent_key, timeout_seconds)`
Выполняет HTTP-запрос и возвращает структурированный результат для UI/API.

---

## 5.8 `optimizer.py` — LLM-оптимизация текста

### Цель модуля
Итеративно улучшать конкретные проблемные зоны из аналитики, избегая полной перегенерации текста и сохраняя стиль/повествование.

### Служебные функции подготовки
- `_tokenize` — токенизация строки.
- `_filter_stopwords` — удаление stop-слов.
- `_split_sentences` — сегментация на предложения.
- `_max_sentences_for_level` — лимиты длины кандидата по каскаду.
- `_validate_candidate_text` — pre-check качества (пустота, дубль слова/сущности, подозрительные токен-склейки, превышение лимита предложений).

### Снимки аналитики
- `_build_analysis_snapshot` — пересчет `/analyze` локально.
- `_build_semantic_snapshot` — пересчет semantic среза локально.

### Скоринг и выбор цели
- `_compute_metrics` — единый набор метрик состояния:
  - composite score
  - `bert_low_count`
  - `bert_phrase_scores`
  - `bm25_remove_count`
  - сигналы n-gram/semantic
  - `title_bert_score`
  - `semantic_gap_count`, `semantic_gap_sum`, `semantic_gap_terms`
- `_choose_optimization_goal` — выбирает приоритетную проблему.
  - для BERT-целей используется порог `BERT_TARGET_THRESHOLD=0.7` (допустимый рабочий минимум может быть снижен до `0.65`), без конкурентного override;
- `_choose_sentence_idx` — выбирает релевантный чанк для правки.

### Параметры Semantic Gap в оптимизаторе
- `SEMANTIC_GAP_TOLERANCE_PCT = 0.15` — допускается отклонение до ~15% от target, без штрафа.
- `SEMANTIC_GAP_MIN_ABS = 3.0` — игнорируются микрошумы с маленькой абсолютной разницей.
- Gap считается значимым, если одновременно:
  - `competitor_avg_weight > target_weight * (1 + tolerance)`
  - `competitor_avg_weight - target_weight >= min_abs`

Это убирает пере-жесткую подгонку к среднему конкуренту и снижает ложные колебания `semantic_gap_count`.

### Генерация кандидатов
- `_llm_edit_chunk` — отправляет structured prompt в OpenAI-compatible API.
  - учитывает `cascade_level` и тип операции (`rewrite`/`insert`)
  - явно требует грамматически корректный и естественный текст
  - ограничивает число предложений по уровню

### Применение правок
- `_replace_span` — замена диапазона предложений.
- `_insert_after` — вставка после диапазона.

### Принятие/отклонение кандидата
- `_goal_improved`:
  - для BERT: улучшение score целевой фразы минимум на `BERT_GOAL_DELTA_MIN=0.005` **или** снижение `bert_low_count`;
  - для других целей: профильные метрики улучшения.
- `_is_candidate_valid`:
  - hard constraints (не ухудшать критичные метрики сверх допустимого);
  - режимы `conservative/balanced/aggressive` задают пороги регрессии;
  - решение учитывает и `goal_improved`, и общий `delta_score`.

### Главная функция `optimize_text`
Итерационный цикл:
1. baseline metrics.
2. выбрать goal.
3. выбрать пул чанков и операцию каскада.
   - на шаг выбирается несколько span-кандидатов (multi-chunk selection), а не один;
   - ранжирование учитывает `focus_terms/avoid_terms`, chunk-level relevance и шумовые эвристики (menu/CTA/header penalties);
   - используется `attempt_cursor` по цели и `attempted_spans`, чтобы избежать циклов по одному и тому же участку.
4. сгенерировать `N` кандидатов для каждого выбранного span.
5. pre-validation (формат/качество/длины).
6. chunk-level оценка:
   - вычисляется `chunk_goal_delta` (релевантность чанка до/после к текущей цели);
   - кандидат помечается `local_chunk_improved`, если прирост выше порога цели.
7. document-level оценка:
   - полный пересчет метрик для всего текста;
   - проверка глобальных ограничений через `_is_candidate_valid`.
8. staged acceptance:
   - если кандидат улучшает цель/общий score и проходит глобальные ограничения — `applied`;
   - если локально улучшает чанк, но глобально не проходит — кандидат кладется в queue.
   - для BERT учитывается прямой документный `bert_phrase_delta` по целевой фразе: даже небольшой положительный рост считается полезным шагом при отсутствии регрессий по guardrails.
   - если нет `promotable` кандидата, но есть guardrail-valid кандидат с `local_chunk_improved`, применяется режим `applied_local_progress`: правка принимается локально и оптимизация переходит к следующему чанку (накопительная стратегия).
9. batch-логика queue:
   - optimizer пробует совместно применить комбинации из 2..4 локально сильных не конфликтующих правок;
   - batch принимается только при прохождении глобальных ограничений и положительном совокупном локальном приросте.
10. при серии неудач эскалировать каскад (`L1 -> L2 -> L3 -> L4`), при успехе сбрасывать на `L1`.
   - `L1`: локальный rewrite (обычно 1 предложение),
   - `L2`: rewrite расширенного окна (2-3 предложения, несколько вариантов радиусов),
   - `L3`: insert bridge (вставка) с возможным fallback на rewrite,
   - `L4`: более широкий rewrite окна (до 5 предложений с вариативным охватом).
11. вести подробный лог по каждому кандидату.
   - в debug-таблице фиксируются и chunk-level сигналы (`local+`, `chunk Δ`, `rel before->after`) наряду с глобальными (`Δ score`, `valid`, `goal+`);
   - для каждого кандидата сохраняется `llm_prompt_debug` (операция, цель, фокус-термы, chunk и ближайший контекст), что позволяет анализировать фактический вход в LLM.
   - также сохраняется `metrics_delta` (вклад BM25/BERT/Semantic/N-gram/Title в общий сдвиг), включая `semantic_gap_sum` и изменение состава gap-термов (`semantic_gap_terms_added/removed`), чтобы видеть, за счет чего падает или растет `score`.

---

## 6) Frontend (`templates/index.html`) — сценарии и функции

## 6.1 Ввод данных и URL import
- `loadUserAgentOptions` — загрузка пресетов UA.
- `fetchUrlPayload` — запрос к URL API.
- `fetchTargetFromUrl` — заполнение target text/title из URL.
- `fetchCompetitorsFromUrls` — массовое заполнение competitors.

Ручной ввод всегда остается рабочим fallback-сценарием.

## 6.2 Локальное сохранение проекта
- `saveProject` — экспорт JSON.
- `loadProject` — загрузка JSON.
- `applyProjectData` — восстановление полей и результатов.
- `clearProject` — новый проект/сброс.

API-ключ оптимизатора в persist-состояние не сохраняется.

## 6.3 Запуск аналитики и отрисовка
- `runAnalysis`
- `runSemanticAnalysis`
- `runSemanticSearch`
- `renderResults`
- `renderSemanticResults`
- `renderTitleResults`
- `showNgramTable`

## 6.4 Сводка и оптимизатор
- `renderActionSummary` — агрегирует рекомендации BERT/BM25/N-grams/Title/Semantic в табличный формат.
- `runLlmOptimization` — запуск оптимизации.
- `renderOptimizerResults` — итог и debug-лог по шагам/кандидатам.
- `applyOptimizedText` — перенос optimized текста в `target_text`.

## 6.5 Сортировка таблицы мощных терминов
- `setSemanticTermSortBy`
- `toggleSemanticTermSortDir`

Поддерживаются сортировки по:
- `Мой вес`
- `Avg K`
- `Freq (X/Y)` (с приоритетом большего `X` при одинаковом `Y`)

---

## 7) Данные и модели (`models.py`)

Ключевые модели:
- `AnalysisRequest`, `AnalysisResponse`
- `SemanticAnalyzeRequest`, `SemanticAnalyzeResponse`
- `SemanticSearchRequest`, `SemanticSearchResponse`
- `UrlFetchRequest`, `UrlFetchResponse`, `UserAgentInfo`, `UserAgentsResponse`
- `OptimizerRequest`, `OptimizerResponse`

Роль моделей:
- жестко фиксируют API-контракты;
- упрощают валидацию;
- создают стабильный интерфейс между frontend/backend.

---

## 8) Практические вычислительные принципы

1. **Согласованная нормализация**  
   Одни и те же правила токенизации/лемматизации используются в нескольких модулях, чтобы избежать рассинхронизации метрик.

2. **Локальные правки вместо полной перегенерации**  
   Оптимизатор меняет только локальные участки текста и проверяет эффект после каждой правки.

3. **Многокритериальная защита**  
   Кандидат не принимается, если улучшение одной метрики достигается ценой неприемлемой деградации других.

4. **Объяснимость**  
   Подробный лог итераций фиксирует baseline шага, кандидатов, причины отклонения и примененный вариант.

---

## 9) Рекомендации по воспроизведению приложения по документации

Минимальный путь воспроизведения:
1. Поднять FastAPI-приложение с endpoint-ами из раздела 4.
2. Реализовать `logic.py` и `semantic_*` модули с описанными формулами и пайплайнами.
3. Сделать frontend с соответствующими сценариями (`runAnalysis`, `runSemanticAnalysis`, `runLlmOptimization`).
4. Добавить URL extractor и LLM optimizer как отдельные backend сервисы.
5. Проверить контракты ответов, чтобы UI-таблицы и вкладки заполнялись без адаптеров.

---

## 10) Эксплуатация и деплой (Hugging Face)

- Рекомендуемый режим: lazy загрузка моделей.
- При проблемах типа `Could not resolve host: huggingface.co` рассматривать как внешнюю инфраструктурную проблему DNS/egress.
- Для диагностики сверять:
  - `repo_sha` и `runtime_sha`
  - `runtime_stage`
- При зависании сборки использовать повторный trigger-build.

---

## 11) Smoke-check после любых изменений

1. `python -m py_compile app.py logic.py semantic_graph.py search.py optimizer.py url_fetcher.py`
2. Проверка endpoint-ов:
   - `/analyze`
   - `/api/v1/semantic/analyze`
   - `/api/v1/semantic/search`
   - `/api/v1/url/user-agents`
   - `/api/v1/url/fetch`
   - `/api/v1/optimizer/run`
3. Проверка UI:
   - табы рендерятся;
   - сортировки и таблицы работают;
   - URL import заполняет text/title;
   - save/load/new project работают;
   - оптимизатор пишет лог и применяет текст.