optimizer: per-goal deficit-based iteration and candidate budget

docs/FULL_FUNCTIONAL_DOCUMENTATION.md

@@ -472,7 +472,7 @@ HTML extraction pipeline:
 - `_is_stage_complete` для `bert`:
   - этап считается завершённым только когда **каждая** отслеживаемая ключевая фраза достигает `bert_stage_target` (проверка по `min(bert_phrase_scores)`);
   - достижение порога одной «сильной» фразой больше не завершает BERT-этап.
-  - унифицированный цикл по целям: на каждой стадии для **каждой** найденной цели/фразы действует одинаковый бюджет `max_iterations` попыток; после исчерпания лимита оптимизатор переходит к следующей цели той же стадии.
+  - унифицированный цикл по целям: базовые параметры запроса `max_iterations` и `candidates_per_iteration` задают «якорь», но для **каждой** цели вычисляется эффективный бюджет (`_per_goal_budget`): число попыток и ширина пула кандидатов **масштабируются по дефициту** до таргета — для BERT по разрыву score до порога, для semantic по `semantic_gap`, для n-gram по отставанию/перегрузу относительно целевого счётчика, для BM25 по «лишним» вхождениям слова, для title по разрыву `title_bert_score`. После исчерпания лимита по текущей цели оптимизатор переходит к следующей цели той же стадии.
 - `_validate_candidate_text`:
   - отклоняет некачественные/спамные кандидаты (дубли слов/сущностей, подозрительные склейки токенов);
   - добавляет anti-stuffing фильтр для цели BERT (повторы exact phrase и чрезмерные повторы focus-термов).
@@ -480,7 +480,7 @@ HTML extraction pipeline:
 ### Главная функция `optimize_text`
 Итерационный цикл:
 1. baseline metrics.
-   - общий бюджет шагов оценивается как `sum(цели_стадии × max_iterations)` по всем стадиям (с верхней отсечкой в коде), то есть масштабируется по числу реально требующих улучшения целей.
+   - общий бюджет шагов оценивается как **сумма эффективных итераций по всем целям** (`_estimate_total_loop_budget`: для каждой цели — `_per_goal_budget`, затем сумма по стадиям с верхней отсечкой), то есть масштабируется и по числу целей, и по величине отставания от таргета. В SSE-событии `step_start` дополнительно передаются `goal_budget_iter` и `goal_budget_candidates` для текущей цели.
 2. выбрать goal.
 3. выбрать пул чанков и операцию каскада.
    - **Этап `title`:** если средняя BERT-близость Title к ключам (`title_bert_score`) ниже порога (`TITLE_TARGET_THRESHOLD` ≈ 0.65), цель — **только переписать текст из поля Title** (`target_title`), а не абзац основного текста. LLM получает текущий title, выдержку из body и ключевые слова; метрики пересчитываются с новым title. Пакетные правки по body с title не смешиваются.
@@ -490,7 +490,7 @@ HTML extraction pipeline:
    - для **n-gram** целей предложения ранжируются через **скользящие перекрывающиеся окна** из 2–4 предложений (шаг 1): каждому предложению присваивается лучший балл среди окон, оценка штрафует локальные повторы фразы и шумовые блоки;
    - для BERT-целей ранжирование не ограничивается участками с already-present вхождениями: дополнительно приоритизируются релевантные участки с недопредставленными core-термами, где их можно добавить естественно;
    - используется `attempt_cursor` по цели и `attempted_spans`, чтобы избежать циклов по одному и тому же участку.
-4. сгенерировать `N` кандидатов для каждого выбранного span.
+4. сгенерировать `N` кан��идатов для каждого выбранного span (`N` зависит от эффективного бюджета кандидатов для цели и каскада, см. `_per_goal_budget` и деление по span).
 5. pre-validation (формат/качество/длины).
 6. chunk-level оценка:
    - вычисляется `chunk_goal_delta` (релевантность чанка до/после к текущей цели);

optimizer.py

@@ -578,7 +578,16 @@ def _collect_optimization_goals(
             if not phrase:
                 continue
             focus_terms = _filter_stopwords(_tokenize(phrase), language)[:4]
-            goals.append({"type": "bert", "label": phrase, "focus_terms": focus_terms, "avoid_terms": []})
+            goals.append(
+                {
+                    "type": "bert",
+                    "label": phrase,
+                    "focus_terms": focus_terms,
+                    "avoid_terms": [],
+                    "bert_phrase_score": float(row.get("my_max_score", 0) or 0.0),
+                    "bert_target": float(bert_stage_target),
+                }
+            )
 
     bm25_remove = [x for x in (analysis.get("bm25_recommendations") or []) if x.get("action") == "remove"]
     if len(bm25_remove) >= 4:
@@ -586,7 +595,16 @@ def _collect_optimization_goals(
             word = str(row.get("word", "")).strip()
             if not word:
                 continue
-            goals.append({"type": "bm25", "label": f"reduce spam: {word}", "focus_terms": [], "avoid_terms": [word]})
+            goals.append(
+                {
+                    "type": "bm25",
+                    "label": f"reduce spam: {word}",
+                    "focus_terms": [],
+                    "avoid_terms": [word],
+                    "bm25_count": int(row.get("count", 0) or 0),
+                    "bm25_word": word,
+                }
+            )
 
     # Semantic keyword gaps
     lang_stop = STOP_WORDS.get(language, STOP_WORDS["en"])
@@ -609,8 +627,16 @@ def _collect_optimization_goals(
         if _is_semantic_gap(target_w, comp_w):
             candidate_rows.append((term, gap))
     if candidate_rows:
-        for term, _gap in sorted(candidate_rows, key=lambda x: x[1], reverse=True)[:12]:
-            goals.append({"type": "semantic", "label": term, "focus_terms": [term], "avoid_terms": []})
+        for term, gap in sorted(candidate_rows, key=lambda x: x[1], reverse=True)[:12]:
+            goals.append(
+                {
+                    "type": "semantic",
+                    "label": term,
+                    "focus_terms": [term],
+                    "avoid_terms": [],
+                    "semantic_gap": float(gap),
+                }
+            )
 
     # N-gram balancing (toward competitor average with tolerance policy).
     ngram_rows = _build_ngram_stage_rows(analysis, keywords, language)
@@ -638,16 +664,93 @@ def _collect_optimization_goals(
         and title_target_score is not None
         and float(title_target_score) < TITLE_TARGET_THRESHOLD
     ):
-        goals.append({
-            "type": "title",
-            "label": "title alignment",
-            "focus_terms": _filter_stopwords(_tokenize(" ".join(keywords[:8])), language)[:8],
-            "avoid_terms": [],
-        })
+        goals.append(
+            {
+                "type": "title",
+                "label": "title alignment",
+                "focus_terms": _filter_stopwords(_tokenize(" ".join(keywords[:8])), language)[:8],
+                "avoid_terms": [],
+                "title_bert_score": float(title_target_score) if title_target_score is not None else None,
+                "title_target": float(TITLE_TARGET_THRESHOLD),
+            }
+        )
 
     return [g for g in goals if g.get("type") == stage]
 
 
+def _per_goal_budget(
+    goal: Dict[str, Any],
+    max_iterations: int,
+    candidates_per_iteration: int,
+    bert_stage_target: float,
+) -> Tuple[int, int]:
+    """
+    Scale per-goal iteration and candidate budgets by how far the metric is from its target.
+    Returns (effective_max_iterations_for_this_goal, effective_candidates_per_iteration).
+    """
+    t = str(goal.get("type", "") or "")
+    raw = 0.0
+
+    if t == "bert":
+        sc = float(goal.get("bert_phrase_score", 0.0) or 0.0)
+        tgt = float(goal.get("bert_target", bert_stage_target) or bert_stage_target)
+        raw = max(0.0, (tgt - sc) / max(tgt, 1e-6))
+    elif t == "ngram":
+        ca = float(goal.get("ngram_comp_avg", 0.0) or 0.0)
+        tc = float(goal.get("ngram_target_count", 0.0) or 0.0)
+        if str(goal.get("ngram_direction", "increase")) == "increase":
+            need = max(0.0, ca - tc)
+            raw = min(1.0, need / max(ca, 1e-6))
+        else:
+            need = max(0.0, tc - ca)
+            raw = min(1.0, need / max(tc, 1e-6))
+    elif t == "semantic":
+        gap = float(goal.get("semantic_gap", 0.0) or 0.0)
+        raw = min(1.0, gap / max(SEMANTIC_GAP_MIN_ABS * 4.0, 1e-6))
+    elif t == "bm25":
+        c = int(goal.get("bm25_count", 0) or 0)
+        raw = min(1.0, max(0, c - 1) / 8.0)
+    elif t == "title":
+        ts = goal.get("title_bert_score")
+        if ts is None:
+            raw = 0.5
+        else:
+            tgt = float(goal.get("title_target", TITLE_TARGET_THRESHOLD) or TITLE_TARGET_THRESHOLD)
+            raw = max(0.0, (tgt - float(ts)) / max(tgt, 1e-6))
+    else:
+        raw = 0.0
+
+    iter_mult = 1.0 + 2.0 * min(1.0, raw)
+    cand_mult = 1.0 + 1.0 * min(1.0, raw)
+    eff_iter = max(1, min(int(round(max_iterations * iter_mult)), max_iterations * 3))
+    eff_cand = max(1, min(int(round(candidates_per_iteration * cand_mult)), 5))
+    return eff_iter, eff_cand
+
+
+def _estimate_total_loop_budget(
+    analysis: Dict[str, Any],
+    semantic: Dict[str, Any],
+    keywords: List[str],
+    language: str,
+    max_iterations: int,
+    candidates_per_iteration: int,
+    bert_stage_target: float,
+) -> int:
+    total = 0
+    for st in STAGE_ORDER:
+        for g in _collect_optimization_goals(
+            analysis,
+            semantic,
+            keywords,
+            language,
+            stage=st,
+            bert_stage_target=bert_stage_target,
+        ):
+            ei, _ = _per_goal_budget(g, max_iterations, candidates_per_iteration, bert_stage_target)
+            total += ei
+    return min(480, max(1, total))
+
+
 def _choose_sentence_idx(sentences: List[str], focus_terms: List[str], avoid_terms: List[str], language: str) -> int:
     if not sentences:
         return 0
@@ -1507,8 +1610,7 @@ def optimize_text(
         baseline_analysis, baseline_semantic, keywords, language, bert_stage_target=bert_stage_target
     )
 
-    # Unified per-goal budget for all stages:
-    # total steps = sum(goals_in_stage * max_iterations)
+    # Per-goal iteration budget scales with deficit; total loop steps = sum(effective iters per goal).
     baseline_goal_counts = {
         st: len(
             _collect_optimization_goals(
@@ -1523,8 +1625,15 @@ def optimize_text(
         for st in STAGE_ORDER
     }
     ngram_row_count = int(baseline_goal_counts.get("ngram", 0))
-    estimated_total = sum(int(c) * int(max_iterations) for c in baseline_goal_counts.values())
-    total_loop_steps = min(240, max(1, estimated_total))
+    total_loop_steps = _estimate_total_loop_budget(
+        baseline_analysis,
+        baseline_semantic,
+        keywords,
+        language,
+        max_iterations,
+        candidates_per_iteration,
+        bert_stage_target,
+    )
 
     current_text = target_text
     current_title = (target_title or "").strip()
@@ -1621,8 +1730,12 @@ def optimize_text(
         goal_index = int(state.get("goal_index", 0))
         attempt_count = int(state.get("attempt_count", 0))
 
-        # Advance across goals that exhausted per-goal iteration budget.
-        while goal_index < len(goals_for_stage) and attempt_count >= max_iterations:
+        # Advance across goals that exhausted per-goal iteration budget (scaled by deficit).
+        while goal_index < len(goals_for_stage):
+            g_try = goals_for_stage[goal_index]
+            eff_max_iter, _ = _per_goal_budget(g_try, max_iterations, candidates_per_iteration, bert_stage_target)
+            if attempt_count < eff_max_iter:
+                break
             goal_index += 1
             attempt_count = 0
 
@@ -1634,13 +1747,14 @@ def optimize_text(
                     "step": step + 1,
                     "status": "stage_skipped",
                     "stage": active_stage,
-                    "reason": f"All goals exhausted for stage '{active_stage}' (max_iterations={max_iterations} per goal).",
+                    "reason": f"All goals exhausted for stage '{active_stage}' (per-goal iteration budget).",
                 }
             )
             stage_goal_cursor[active_stage] = {"goal_index": goal_index, "attempt_count": attempt_count}
             continue
 
         goal = goals_for_stage[goal_index]
+        eff_max_iter, eff_cand = _per_goal_budget(goal, max_iterations, candidates_per_iteration, bert_stage_target)
         attempt_count += 1
         stage_goal_cursor[active_stage] = {"goal_index": goal_index, "attempt_count": attempt_count}
         if goal["type"] == "none":
@@ -1664,6 +1778,8 @@ def optimize_text(
             goal_type=goal.get("type"),
             goal_label=goal.get("label"),
             score=current_metrics.get("score"),
+            goal_budget_iter=eff_max_iter,
+            goal_budget_candidates=eff_cand,
         )
 
         goal_key = f"{goal.get('type', '')}:{goal.get('label', '')}".strip().lower()
@@ -1706,7 +1822,7 @@ def optimize_text(
                 phrase_strategy_mode,
                 "title",
                 str(goal.get("label", "")),
-                candidates_per_iteration,
+                eff_cand,
             )
             for strategy_variant in strategy_plan:
                 candidate_idx += 1
@@ -1913,7 +2029,7 @@ def optimize_text(
                 break
 
             span_trials = 2 if cascade_level <= 2 else 3
-            local_candidates = candidates_per_iteration if cascade_level <= 2 else min(6, candidates_per_iteration + 1)
+            local_candidates = eff_cand if cascade_level <= 2 else min(6, eff_cand + 1)
             span_trials_eff = span_trials
 
             for st in range(span_trials):