Expand full functional documentation with algorithmic details.

Rewrite the documentation as an implementation-grade reference covering architecture, API contracts, module-level function logic, formulas, optimizer decision rules, frontend workflows, and reproducibility guidance.

Made-with: Cursor

docs/FULL_FUNCTIONAL_DOCUMENTATION.md

@@ -1,317 +1,562 @@
-# SEO AI Editor — Полная документация функционала и логики
+# SEO AI Editor — исчерпывающая документация функционала, логики и алгоритмики
 
-Документ описывает текущее состояние проекта целиком: архитектуру, API, логику расчётов, фронтенд-сценарии, сохранение проектов и особенности деплоя.
+Документ описывает приложение как инженерную спецификацию: что делает каждый модуль, какие данные принимает и возвращает, какие формулы использует, какие ограничения применяет и как воспроизвести поведение системы без чтения исходного кода.
 
 ---
 
-## 1) Назначение системы
+## 1) Концепция приложения
 
-Приложение объединяет два больших контура:
+`SEO AI Editor` объединяет два аналитических контура и один контур улучшения текста:
 
-1. **SEO-анализ текста** (`/analyze`)
-   - N-граммы (1-4)
-   - BM25-рекомендации (add/remove/ok)
-   - BERT-семантика
+1. **SEO-контур** (`POST /analyze`)
    - Word Count (total/significant)
-   - Title analyzer
-
-2. **Semantic Core** (`/api/v1/semantic/*`)
-   - Семантический граф понятий
-   - Веса узлов/связей 1..100
-   - Гипертекстовая разметка
-   - Реферат
-   - Смысловой поиск (по словам и фразам)
-   - Сравнение с конкурентами
+   - 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) Текущая структура проекта
+## 2) Архитектура и ответственность файлов
 
-- `app.py` — FastAPI entrypoint, роутинг, orchestration.
-- `logic.py` — основная SEO-логика (spaCy, n-grams, BM25, BERT, Title).
-- `models.py` — Pydantic-модели запросов/ответов.
-- `nlp_processor.py` — разбор текста для Semantic Core.
-- `semantic_graph.py` — построение semantic graph, веса и связи.
-- `highlighter.py` — разметка текста по весам узлов.
-- `summarizer.py` — реферирование.
-- `search.py` — смысловой поиск.
-- `templates/index.html` — весь frontend (UI + JS).
-- `requirements.txt`, `Dockerfile`.
+- `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`
+Поддерживаемые языки анализа:
+- `ru`, `en`, `de`, `es`, `it`, `pl`, `pt`
 
-Модели spaCy задаются в `logic.py` через `MODEL_NAMES`.
+Языки задаются кодом и сопоставляются с spaCy-моделями в `logic.py` (`MODEL_NAMES`).
 
 ---
 
-## 4) Backend API (актуально)
+## 4) Backend API и контракты
 
-## 4.1 `POST /analyze` (SEO pipeline)
+## 4.1 `POST /analyze`
 
-Вход (`AnalysisRequest`):
-- `target_text`
-- `competitors[]`
-- `keywords[]`
-- `language`
-- `target_title`
-- `competitor_titles[]`
+### Назначение
+Комплексный SEO-анализ target-текста относительно конкурентов и ключевых фраз.
 
-Выход (`AnalysisResponse`):
+### Вход (`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`
 
-### Внутренний пайплайн
-1. `count_words()` для target/competitors.
-2. `calculate_ngram_stats()`.
-3. `parse_keywords()` + `calculate_bm25_recommendations()`.
-4. `perform_bert_analysis()`.
-5. `analyze_title()`.
+### Оркестрация в `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`
 
-Вход (`SemanticAnalyzeRequest`):
-- `text`
-- `competitors[]`
-- `language`
-- `threshold` (порог подсветки)
-- `compression_ratio` (доля реферата)
-
-Выход (`SemanticAnalyzeResponse`):
-- `target` — полный semantic результат по target документу
-- `competitors[]` — результаты по каждому конкуренту
-- `comparison` — сравнительные агрегаты:
+### Назначение
+Построение 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`
+
+### Логика таблицы `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`):
+### Назначение
+Смысловой поиск по документу через граф.
+
+### Вход (`SemanticSearchRequest`)
 - `query_text`
 - `text`
 - `language`
 - `top_n`
 
-Выход (`SemanticSearchResponse`):
-- `results[]` с полями:
-  - `lemma`
-  - `score` (1..100)
-  - `type` (`word` / `phrase`)
+### Выход (`SemanticSearchResponse`)
+- `results[]`: `lemma`, `score (1..100)`, `type (word|phrase)`
 
 ---
 
-## 5) Подробно по модулям и формулам
-
-## 5.1 `logic.py` (SEO контур)
-
-### Ключевые функции
-- `load_model_if_missing(lang)` — lazy load spaCy.
-- `get_doc(text, lang)` — spaCy Doc.
-- `is_valid_token(t)` — фильтр полезных токенов.
-- `get_lemmas_flat(text, lang)` — плоские леммы.
-- `generate_ngrams_safe(text, lang, n)` — Smart Window:
-  - N считается по значимым словам,
-  - стоп-слова внутри фразы сохраняются,
-  - стенки (punct/num/sym) режут фразу.
-- `count_words(text, lang)` — total/significant.
-- `calculate_ngram_stats(...)` — 1..4 граммы + per-competitor детали.
-- `calculate_bm25_recommendations(...)` — BM25 на n-grams, mirror principle.
-- `perform_bert_analysis(...)` — semantic similarity по chunks.
-- `analyze_title(...)` — title длина/ngrams/coverage/bert.
-
-### BM25 (в текущей реализации)
-- ключевые фразы декомпозируются в 1/2/3-граммы через ту же функцию, что и корпус;
-- score target сравнивается со средним score competitors;
-- action:
-  - `add`, если target заметно ниже competitors,
-  - `remove`, если заметно выше,
-  - `ok` иначе.
+## 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)`:
-- разбивает на предложения;
-- сохраняет токены:
-  - `text`, `whitespace`, `lemma`, `is_significant`, `is_punct`, `is_space`;
-- возвращает список предложений с:
-  - `raw_text`, `tokens`, `lemmas_clean`.
+### `preprocess_text(text, lang)`
+Преобразует текст в структуру предложений:
+- `raw_text`
+- `tokens[]` с полями `text`, `whitespace`, `lemma`, `is_significant`, `is_punct`, `is_space`
+- `lemmas_clean` (очищенный список лемм)
 
-Назначение: не терять исходное форматирование для UI, но иметь нормализованные данные для math-core.
+Критично: сохранение `whitespace` и исходных токенов позволяет восстановить текст UI-послойно без потери форматирования.
 
 ---
 
-## 5.3 `semantic_graph.py` (семантическое ядро)
+## 5.3 `semantic_graph.py` — математическое ядро
 
-### Текущие принципы
-1. Узлы: **слова + устойчивые фразы**.
-2. Связи: направленные, локальное окно, асимметрия.
-3. Вес связи:
+### `_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`.
-4. Вес узла:
-   - PageRank + connectivity factor,
-   - termness-буст для фраз,
-   - IDF-подобный фактор по охвату предложений,
-   - penalty для слишком общих доменных терминов.
-
-### Дополнительные механики
-- фильтр шумных предложений (`NOISE_PATTERNS`, короткие CTA),
-- каноникализация терминов (`_canonicalize_term`),
-- извлечение фраз через `generate_ngrams_safe`.
+   - затем ограничение в `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(...)`:
-- подсвечивает токены/блоки, если их вес >= threshold;
-- соседние значимые токены склеиваются в один link-block:
-  - `text`
-  - `lemmas[]`
-  - `weight`
+### `generate_markup_for_frontend(sentences_data, word_weights, threshold=50)`
+Маркирует важные блоки:
+- если вес леммы/фразы >= порога, блок становится `is_link=true`;
+- соседние значимые токены могут объединяться в один кликабельный сегмент;
+- во��вращается структура, удобная для реактивного рендера в UI.
 
 ---
 
 ## 5.5 `summarizer.py`
 
-`generate_summary(...)`:
-- score предложения:
-  - `sum(weight(unique_lemmas)) / sqrt(token_count)`
-- отбор top по `compression_ratio`;
-- возврат в хронологическом порядке.
+### `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`
 
-Текущая логика:
-1. Нормализация запроса.
-2. Поиск по фразам (tri/bi) как приоритет.
-3. Затем fallback по леммам-словам.
-4. Расширение соседями графа.
-5. Нормализация в `1..100`.
-6. Маркировка типа результата: `phrase`/`word`.
+### `_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`).
 
 ---
 
-## 6) Frontend: все сценарии
+## 5.7 `url_fetcher.py`
 
-Файл: `templates/index.html`.
+### `get_user_agent_presets()`
+Возвращает список пресетов (Googlebot, Bingbot, ChatGPT user-agent, GPTBot, Chrome Desktop и др.).
 
-### Основные зоны
-- Левый столбец: ввод данных.
-- Правый столбец: вкладки результатов.
+### `_normalize_whitespace(text)`
+Схлопывает лишние пробелы/переводы строк.
 
-### Вкладки
-- `BERT`
-- `BM25`
-- `N-grams`
-- `Title`
-- `Semantic Core`
+### `_normalize_url(url)`
+Приводит URL к валидному виду (схема, trimming).
 
-### JS-функции (ключевые)
-- `runAnalysis()` — запуск `/analyze`.
-- `runSemanticAnalysis()` — запуск `/api/v1/semantic/analyze`.
-- `runSemanticSearch()` — запуск `/api/v1/semantic/search`.
-- `renderResults(...)` — отрисовка SEO вкладок.
-- `renderSemanticResults(...)` — отрисовка Semantic Core.
-- `showNgramTable(...)` — n-gram таблицы.
-- `renderTitleResults(...)` — Title блоки.
+### `_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`
+- `_choose_optimization_goal` — выбирает приоритетную проблему.
+- `_choose_sentence_idx` — выбирает релевантный чанк для правки.
+
+### Генерация кандидатов
+- `_llm_edit_chunk` — отправляет structured prompt в OpenAI-compatible API.
+  - учитывает `cascade_level` и тип операции (`rewrite`/`insert`)
+  - явно требует грамматически корректный и естественный текст
+  - ограничивает число предложений по уровню
+
+### Применение правок
+- `_replace_span` — замена диапазона предложений.
+- `_insert_after` — вставка после диапазона.
+
+### Принятие/отклонение кандидата
+- `_goal_improved`:
+  - для BERT: улучшение score целевой фразы минимум на `0.02` **или** снижение `bert_low_count`;
+  - для других целей: профильные метрики улучшения.
+- `_is_candidate_valid`:
+  - hard constraints (не ухудшать критичные метрики сверх допустимого);
+  - режимы `conservative/balanced/aggressive` задают пороги регрессии;
+  - решение учитывает и `goal_improved`, и общий `delta_score`.
+
+### Главная функция `optimize_text`
+Итерационный цикл:
+1. baseline metrics.
+2. выбрать goal.
+3. выбрать чанк и операцию каскада.
+4. сгенерировать `N` кандидатов.
+5. pre-validation.
+6. full re-score каждого кандидата.
+7. выбрать лучший валидный.
+8. применить или отклонить шаг с причиной.
+9. при серии неудач эскалировать каскад (`L1 -> L2 -> L3 -> L4`), при успехе сбрасывать на `L1`.
+10. вести подробный лог по каждому кандидату.
 
 ---
 
-## 7) Сохранение/загрузка проекта (локально)
+## 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` — новый проект/сброс.
 
-Реализовано полностью на фронтенде:
-- `saveProject()` — экспорт `.json`;
-- `loadProject()` + `applyProjectData(...)` — импорт и восстановление;
-- `clearProject()` — сброс до чистого состояния.
+API-ключ оптимизатора в persist-состояние не сохраняется.
 
-Что сохраняется:
-- все input-поля,
-- semantic параметры,
-- последний `analysis_result`,
-- последний `semantic_result`.
+## 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`)
 
 ---
 
-## 8) Сравнительные таблицы в Semantic Core
+## 7) Данные и модели (`models.py`)
 
-## 8.1 Окно 1 (таблично)
-- узлы (`Node`, `Weight`, `Freq`)
-- связи (`From`, `To`, `P(B|A)`)
+Ключевые модели:
+- `AnalysisRequest`, `AnalysisResponse`
+- `SemanticAnalyzeRequest`, `SemanticAnalyzeResponse`
+- `SemanticSearchRequest`, `SemanticSearchResponse`
+- `UrlFetchRequest`, `UrlFetchResponse`, `UserAgentInfo`, `UserAgentsResponse`
+- `OptimizerRequest`, `OptimizerResponse`
 
-## 8.2 Таблица мощных терминов
-- термин (`word` или `phrase`)
-- мой вес
-- avg вес конкурентов
-- `Freq X/Y`
-- `K1..Kn` веса по конкурентам
+Роль моделей:
+- жестко фиксируют API-контракты;
+- упрощают валидацию;
+- создают стабильный интерфейс между frontend/backend.
 
 ---
 
-## 9) Деплой и эксплуатация (HF)
+## 8) Практические вычислительные принципы
+
+1. **Согласованная нормализация**  
+   Одни и те же правила токенизации/лемматизации используются в нескольких модулях, чтобы избежать рассинхронизации метрик.
 
-Текущий SDK: Docker Space.
+2. **Локальные правки вместо полной перегенерации**  
+   Оптимизатор меняет только локальные участки текста и проверяет эффект после каждой правки.
 
-Практические примечания:
-- startup preload всех spaCy моделей отключен (для устойчивости `cpu-basic`);
-- были инциденты HF infra:
-  - `Initialization step 'init' failed`
-  - `curl: (6) Could not resolve host: huggingface.co`
-  - это platform-side DNS/egress issue, не Python traceback приложения.
+3. **Многокритериальная защита**  
+   Кандидат не принимается, если улучшение одной метрики достигается ценой неприемлемой деградации других.
 
-Рекомендуемая диагностика:
-1. сверять `repo_sha` vs `runtime_sha`,
-2. смотреть `runtime_stage`,
-3. повторный trigger-build (empty commit) при зависании билдера.
+4. **Объяснимость**  
+   Подробный лог итераций фиксирует baseline шага, кандидатов, причины отклонения и примененный вариант.
 
 ---
 
-## 10) Известные ограничения и roadmap
+## 9) Рекомендации по воспроизведению приложения по документации
+
+Минимальный путь воспроизведения:
+1. Поднять FastAPI-приложение с endpoint-ами из раздела 4.
+2. Реализовать `logic.py` и `semantic_*` модули с описанными формулами и пайплайнами.
+3. Сделать frontend с соответствующими сценариями (`runAnalysis`, `runSemanticAnalysis`, `runLlmOptimization`).
+4. Добавить URL extractor и LLM optimizer как отдельные backend сервисы.
+5. Проверить контракты ответов, чтобы UI-таблицы и вкладки заполнялись без адаптеров.
+
+---
 
-### Ограничения текущей версии
-- semantic scoring все еще чувствителен к SEO-шаблонам и доменному шуму;
-- каноникализация пока rule-based;
-- нет отдельной debug-панели для “веса термина по компонентам”.
+## 10) Эксплуатация и деплой (Hugging Face)
 
-### Рекомендуемый roadmap
-1. Debug-режим для объяснимости веса термина.
-2. Расширение каноникализации (brand/entity map по языкам).
-3. Настраиваемые stop/penalty-листы по доменам.
-4. Более строгий phrase-mining с устойчивостью по документам.
-5. UI-фильтры в таблицах терминов (только phrase, только gap против competitors).
+- Рекомендуемый режим: lazy загрузка моделей.
+- При проблемах типа `Could not resolve host: huggingface.co` рассматривать как внешнюю инфраструктурную проблему DNS/egress.
+- Для диагностики сверять:
+  - `repo_sha` и `runtime_sha`
+  - `runtime_stage`
+- При зависании сборки использовать повторный trigger-build.
 
 ---
 
-## 11) Быстрый чек-лист для валидации после изменений
+## 11) Smoke-check после любых изменений
 
-1. `python -m py_compile app.py logic.py semantic_graph.py search.py`
-2. Проверка lints измененных файлов.
-3. Smoke API:
+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`
-4. UI:
-   - вкладки рендерятся,
-   - поиск показывает результаты рядом с формой,
-   - сохранение/загрузка проекта работает.
-5. HF:
-   - `repo_sha == runtime_sha`,
-   - `runtime_stage == RUNNING`.
+   - `/api/v1/url/user-agents`
+   - `/api/v1/url/fetch`
+   - `/api/v1/optimizer/run`
+3. Проверка UI:
+   - табы рендерятся;
+   - сортировки и таблицы работают;
+   - URL import заполняет text/title;
+   - save/load/new project работают;
+   - оптимизатор пишет лог и применяет текст.