Upload 5 files

lumen_formatting.py

@@ -0,0 +1,269 @@
+"""
+lumen_formatting.py — конвертация markdown-подобного текста Lumen в Telegram HTML.
+
+Вынесено из bot.py при аудите технического долга (см. пункт про монолитный
+bot.py на ~3400+ строк): вся эта логика — чистые функции над строками (никакой
+Telegram/Gemini/OpenRouter I/O, никакого рантайм-состояния) и поэтому один из
+самых безопасных кандидатов на выделение в отдельный модуль. bot.py импортирует
+из этого файла все нужные имена напрямую (см. `from lumen_formatting import ...`
+в bot.py) — поведение и публичные имена (`_md_to_html`, `_scrub_latex` и т.д.)
+не изменились, изменилось только физическое расположение кода.
+"""
+
+from __future__ import annotations
+
+import re
+
+_TABLE_SEP_RE = re.compile(r"^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$")
+
+def _split_table_cells(line: str) -> list[str]:
+    s = line.strip()
+    if s.startswith("|"):
+        s = s[1:]
+    if s.endswith("|"):
+        s = s[:-1]
+    return [c.strip() for c in s.split("|")]
+
+def _convert_markdown_tables_to_lists(text: str) -> str:
+    """Telegram не рендерит markdown-таблицы НИ В КАКОМ режиме (ни HTML, ни
+    MarkdownV2) — реальный найденный при тестировании случай: модель (особенно
+    некоторые модели OpenRouter) игнорирует запрет на таблицы из system_prompt.py
+    и всё равно генерирует '|---|---|', пользователь видит вместо аккуратной
+    таблицы сырую кашу из символов "|" построчно. Это защитный (второй) рубеж —
+    находит блоки вида "заголовок + строка-разделитель из дефисов + строки
+    данных" и разворачивает их в список пунктов "**Заголовок:** значение",
+    группируя ячейки одной строки в один пункт списка."""
+    if "|" not in text or "-" not in text:
+        return text
+    lines = text.split("\n")
+    out: list[str] = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        line = lines[i]
+        if "|" in line and i + 1 < n and "-" in lines[i + 1] and _TABLE_SEP_RE.match(lines[i + 1]):
+            header_cells = _split_table_cells(line)
+            if len(header_cells) >= 2:
+                data_rows = []
+                j = i + 2
+                while j < n and "|" in lines[j] and lines[j].strip():
+                    data_rows.append(_split_table_cells(lines[j]))
+                    j += 1
+                if data_rows:
+                    for row in data_rows:
+                        parts = []
+                        for h_idx, header in enumerate(header_cells):
+                            val = row[h_idx] if h_idx < len(row) else ""
+                            if not val:
+                                continue
+                            parts.append(f"**{header}:** {val}" if header else val)
+                        if parts:
+                            out.append("• " + "; ".join(parts))
+                    i = j
+                    continue
+        out.append(line)
+        i += 1
+    return "\n".join(out)
+
+# ── Защитная сетка от сырого LaTeX ──────────────────────────────────────────
+# Реальный найденный при калибровке случай: nemotron-3-nano-30b-a3b:free выдала
+# "\[ S = \pi r^{2}, \]" и "\(x^{2}+y^{2}=r^{2}\)" вместо юникода в ответе про
+# площадь круга — при том что system_prompt.py прямо запрещает LaTeX и явно
+# перечисляет юникод-замены (см. раздел ФОРМАТИРОВАНИЕ). Инструкция в промпте —
+# первый (и ненадёжный) рубеж; это — второй, тот же принцип, что уже применяется
+# к случайным HTML-тегам в Phase 0 ниже: не полагаемся только на послушание
+# модели, страхуем детерминированной пост-обработкой.
+_LATEX_SUPERSCRIPT_MAP = {"0": "⁰", "1": "¹", "2": "²", "3": "³", "4": "⁴", "5": "⁵", "6": "⁶", "7": "⁷", "8": "⁸", "9": "⁹", "+": "⁺", "-": "⁻", "n": "ⁿ"}
+_LATEX_SUBSCRIPT_MAP = {"0": "₀", "1": "₁", "2": "₂", "3": "₃", "4": "₄", "5": "₅", "6": "₆", "7": "₇", "8": "₈", "9": "₉"}
+# Порядок важен: многобуквен��ые команды (\times, \infty...) должны замениться
+# ДО одиночного \t/\i и т.п., иначе оставшийся общий "\команда -> без бэкслеша"
+# в конце срежет их раньше времени. dict сохраняет порядок вставки в Python 3.7+.
+_LATEX_SYMBOL_MAP: dict[str, str] = {
+    r"\times": "×", r"\cdot": "·", r"\approx": "≈", r"\infty": "∞",
+    r"\leq": "≤", r"\le": "≤", r"\geq": "≥", r"\ge": "≥", r"\neq": "≠", r"\ne": "≠",
+    r"\rightarrow": "→", r"\Rightarrow": "⇒", r"\to": "→",
+    r"\forall": "∀", r"\exists": "∃", r"\emptyset": "∅", r"\cup": "∪", r"\cap": "∩", r"\in": "∈",
+    r"\pi": "π", r"\pm": "±", r"\mp": "∓", r"\sum": "∑", r"\int": "∫", r"\prod": "∏",
+    r"\alpha": "α", r"\beta": "β", r"\gamma": "γ", r"\Gamma": "Γ", r"\theta": "θ",
+    r"\lambda": "λ", r"\mu": "μ", r"\sigma": "σ", r"\Sigma": "Σ", r"\delta": "δ", r"\Delta": "Δ",
+    r"\phi": "φ", r"\omega": "ω", r"\Omega": "Ω",
+}
+
+def _latex_superscript(m: re.Match) -> str:
+    return "".join(_LATEX_SUPERSCRIPT_MAP.get(ch, ch) for ch in m.group(1))
+
+def _latex_subscript(m: re.Match) -> str:
+    return "".join(_LATEX_SUBSCRIPT_MAP.get(ch, ch) for ch in m.group(1))
+
+def _scrub_latex(text: str) -> str:
+    """Конвертирует сырой LaTeX в обычный юникод-текст (или снимает разметку,
+    если точный эквивалент неизвестен) — ДОЛЖНА вызываться уже после того, как
+    настоящие блоки/спаны кода вырезаны и заменены плейсхолдерами (см. Phase 1 в
+    _md_to_html), иначе легитимный код с обратным слэшем (regex-паттерны, пути
+    Windows и т.п.) был бы испорчен."""
+    if "\\" not in text and "$" not in text:
+        return text
+    # Разделители-обёртки $$...$$, \[...\], \(...\) — убираем сами разделители,
+    # оставляя содержимое для дальнейшей посимвольной замены ниже. Одиночный
+    # "$...$" (инлайн-математика в LaTeX) НАМЕРЕННО не обрабатывается: найдено
+    # при код-ревью — если в одном сообщении встречаются и сумма в долларах, и
+    # настоящая формула ("цена $100, а формула $x^2$ рядом"), первый "$" суммы
+    # ошибочно спаривается с первым "$" формулы, и результат становится ХУЖЕ
+    # исходного (обрезанные суммы плюс осиротевший "$" в хвосте формулы — то есть
+    # именно тот класс "лишнего символа", который эта защитная сетка должна
+    # убирать, а не плодить). "$$...$$" безопаснее: два подряд идущих "$" без
+    # пробела между ними практически никогда не возникают в обычном тексте с
+    # суммами денег, поэтому ложные срабатывания здесь на практике не встречаются.
+    text = re.sub(r"\\\[(.*?)\\\]", r"\1", text, flags=re.DOTALL)
+    text = re.sub(r"\\\((.*?)\\\)", r"\1", text, flags=re.DOTALL)
+    text = re.sub(r"\$\$(.*?)\$\$", r"\1", text, flags=re.DOTALL)
+    # \frac{a}{b} -> a/b (одноуровневая вложенность, самый частый случай)
+    text = re.sub(r"\\d?frac\{([^{}]*)\}\{([^{}]*)\}", r"\1/\2", text)
+    # \sqrt{x} -> √x, \sqrt[n]{x} -> ⁿ√x
+    text = re.sub(r"\\sqrt\[([^\]]*)\]\{([^{}]*)\}", r"\1√\2", text)
+    text = re.sub(r"\\sqrt\{([^{}]*)\}", r"√\1", text)
+    for cmd, repl in _LATEX_SYMBOL_MAP.items():
+        text = text.replace(cmd, repl)
+    # x^{2} / x^2 -> x², x_{2} / x_2 -> x₂ — только короткие индексы/степени,
+    # чтобы случайно не тронуть код вида a^b в языках, где это не степень.
+    # ОСТАТОЧНЫЙ EDGE-CASE (осознанно принят, не фиксим): замена не привязана к
+    # "$"/"\("-разделителям и срабатывает на голое "x^2" где угодно в тексте вне
+    # код-блоков/код-спанов (те уже вырезаны на предыдущем шаге). Если модель
+    # без backtick-форматирования упомянет побитовый XOR в прозе ("5^3 даёт..."),
+    # это тоже превратится в "5³" — потеряв смысл XOR. Системный промпт и так
+    # требует оформлять код через `бэктики`/```блоки```, поэтому легитимные
+    # примеры кода уже защищены; голый "^" в чистой прозе почти всегда всё же
+    # означает именно степень, а не XOR — компромисс в пользу частого случая.
+    text = re.sub(r"\^\{([0-9n+\-]{1,3})\}", _latex_superscript, text)
+    text = re.sub(r"\^([0-9n])(?![0-9])", _latex_superscript, text)
+    text = re.sub(r"_\{([0-9]{1,3})\}", _latex_subscript, text)
+    text = re.sub(r"_([0-9])(?![0-9])", _latex_subscript, text)
+    # Оставшиеся одиночные \command без известного юникод-эквивалента — просто
+    # снимаем бэкслеш, чтобы пользователь не видел сырое "\int"/"\mathbb" и т.п.
+    text = re.sub(r"\\([a-zA-Z]+)", r"\1", text)
+    return text
+
+# ── Маркеры списков "- текст" / "* текст" в начале строки → "• текст" ───────
+# Реальный найденный при калибровке пробел: _md_to_html конвертирует **bold**,
+# *italic*, `code`, ```блоки```, markdown-таблицы — но НЕ конвертирует обычные
+# markdown-маркеры списков, которые system_prompt.py явно предписывает
+# использовать вместо таблиц ("маркированный список"). Модель пишет "- Пункт"
+# или "* Пункт" (оба — совершенно нормальный markdown), а пользователь в
+# Telegram видел литеральные "-"/"*" в начале строки вместо аккуратного "•".
+# Заменяем маркер целиком (а не оставляем "*" как есть) — так исключается и
+# побочный риск, что одиночная "*" в начале строки случайно спарится с другой
+# "*" где-то дальше в тексте и даст неверный *italic*.
+_BULLET_MARKER_RE = re.compile(r"^([ \t]*)[-*][ \t]+", re.MULTILINE)
+
+def _normalize_bullet_markers(text: str) -> str:
+    return _BULLET_MARKER_RE.sub(lambda m: m.group(1) + "• ", text)
+
+def _md_to_html(text: str) -> str:
+    """Convert markdown-like text to Telegram HTML.
+
+    ── КОНТРАКТ ПАЙПЛАЙНА (аудит техдолга, см. пункт про фрагильность этой функции) ──
+    Это цепочка НЕЗАВИСИМЫХ regex-проходов поверх одного текста, а не нормальный
+    парсер с единым деревом разбора — каждый следующий шаг видит результат
+    предыдущего, и порядок шагов принципиален. Сознательное решение НЕ переписывать
+    это на полноценный токенизатор прямо сейчас: пайплайн уже покрыт ~20 тестами,
+    которые ловят именно межфазовые конфликты (см. test_scrub_latex_order_sensitive_
+    replacements_dont_corrupt_each_other, test_md_to_html_does_not_touch_pipes_inside_
+    code_block, test_scrub_latex_does_not_confuse_currency_with_math_delimiters и
+    т.п.) — переписывание на парсер потребовало бы повторно доказать корректность
+    каждого из этих уже отлаженных на реальных инцидентах edge-case'ов заново, без
+    реального выигрыша в надёжности, который можно было бы проверить иначе, чем тем
+    же самым живым продакшен-трафиком, что уже нашёл текущие edge-case'ы. Если в
+    будущем добавится ещё один вид форматирования и очередной межфазовый конфликт
+    станет реальной проблемой (а не гипотетической) — тогда и стоит пересматривать
+    архитектуру, а не превентивно.
+
+    Обязательный порядок фаз (нарушение порядка ломает уже отлаженные edge-case'ы):
+      0. Нормализация сырых HTML-тегов (<b>/<i>/<code>/<pre> и битые self-closing) в
+         markdown-эквивалент — ДО экранирования (шаг 2), иначе легитимные теги от
+         модели превратились бы в видимый мусор "&lt;b&gt;".
+      1. Код-блоки/спаны (```...```/`...`) вырезаются и заменяются плейсхолдерами —
+         ДО LaTeX/таблиц/списков/markdown, иначе обратные слэши и "|"/"-" внутри
+         реального кода (regex, пути Windows, побитовое ИЛИ) были бы испорчены.
+      1.3. LaTeX → юникод (_scrub_latex) — код уже вынесен шагом 1.
+      1.4. Маркеры списков "-"/"* " → "•" (_normalize_bullet_markers) — ДО таблиц,
+           чтобы строка-разделитель таблицы ("|---|---|") успела обработаться первой
+           и не была принята за маркер списка.
+      1.5. Markdown-таблицы → список пунктов (_convert_markdown_tables_to_lists) —
+           код и списки уже обработаны/вырезаны шагами 1/1.4.
+      2. HTML-экранирование остального текста (&/</>).
+      3. Markdown (**bold**/*italic*/~~strike~~) → HTML-теги — ПОСЛЕ экранирования,
+         иначе символы разметки сами могли бы быть экранированы раньше времени.
+      4. Код-блоки/спаны восстанавливаются из плейсхолдеров с собственным
+         экранированием — самыми последними, чтобы шаги 2-3 их не затронули.
+
+    Code blocks are saved first so underscores/asterisks inside them
+    are never treated as italic/bold markers.
+    """
+    if not text:
+        return ""
+
+    # ── Phase 0: нормализация "сырых" HTML-тегов, которые модель иногда пишет
+    # напрямую вместо markdown (несмотря на явную инструкцию в system_prompt.py
+    # использовать только markdown-синтаксис) — без этого такие теги ловятся
+    # escape'ом на шаге 2 и показываются пользователю как видимый мусорный текст
+    # вида "<b>"/"<b/>" прямо в сообщении (реальный найденный при тестировании
+    # баг). Сначала убираем заведомо битые self-closing варианты (напр. "<b/>"),
+    # затем конвертируем корректные парные теги в markdown-эквивалент — дальше
+    # они идут по тому же (уже проверенному) конвейеру, что и обычный markdown.
+    text = re.sub(r"</?(?:b|strong|i|em|u|s|code|pre)\s*/>", "", text, flags=re.IGNORECASE)
+    text = re.sub(r"<(?:b|strong)>(.*?)</(?:b|strong)>", r"**\1**", text, flags=re.IGNORECASE | re.DOTALL)
+    text = re.sub(r"<(?:i|em)>(.*?)</(?:i|em)>", r"*\1*", text, flags=re.IGNORECASE | re.DOTALL)
+    text = re.sub(r"<u>(.*?)</u>", r"\1", text, flags=re.IGNORECASE | re.DOTALL)
+    text = re.sub(r"<s>(.*?)</s>", r"~~\1~~", text, flags=re.IGNORECASE | re.DOTALL)
+    text = re.sub(r"<pre>(.*?)</pre>", lambda m: f"```\n{m.group(1)}\n```", text, flags=re.IGNORECASE | re.DOTALL)
+    text = re.sub(r"<code>(.*?)</code>", r"`\1`", text, flags=re.IGNORECASE | re.DOTALL)
+
+    # ── Phase 1: Save code spans/blocks before any processing ────────────────
+    _saved: dict[str, str] = {}
+    _counter = [0]
+
+    def _save_block(m: re.Match) -> str:
+        key = f"\x00CB{_counter[0]}\x00"
+        _counter[0] += 1
+        _saved[key] = m.group(0)
+        return key
+
+    text = re.sub(r"```[a-zA-Z0-9]*\n.*?\n```", _save_block, text, flags=re.DOTALL)
+    text = re.sub(r"`[^`\n]+`", _save_block, text)
+
+    # ── Phase 1.3: сырой LaTeX → юникод (см. _scrub_latex выше) — код уже
+    # вынесен на предыдущем шаге, поэтому обратные слэши в реальном коде
+    # (regex, пути Windows и т.п.) не затрагиваются.
+    text = _scrub_latex(text)
+
+    # ── Phase 1.4: маркеры списков "- "/"* " → "• " (см. _normalize_bullet_
+    # markers выше) — ДО таблиц и ДО Phase 3, чтобы не путаться с "**bold**" и
+    # чтобы строка-разделитель таблицы ("|---|---|") успела обработаться первой.
+    text = _normalize_bullet_markers(text)
+
+    # ── Phase 1.5: markdown-таблицы → список пунктов (см. _convert_markdown_
+    # tables_to_lists выше) — код уже вынесен на предыдущем шаге, поэтому "|"
+    # внутри кода (например, битовое ИЛИ в Rust/C) сюда не попадёт.
+    text = _convert_markdown_tables_to_lists(text)
+
+    # ── Phase 2: HTML-escape the rest ────────────────────────────────────────
+    text = text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+    # ── Phase 3: Apply markdown ───────────────────────────────────────────────
+    text = re.sub(r"(\*\*|__)(.*?)\1", r"<b>\2</b>", text, flags=re.DOTALL)
+    text = re.sub(r"(\*|_)(.*?)\1", r"<i>\2</i>", text)
+    text = re.sub(r"~~(.*?)~~", r"<s>\1</s>", text)
+
+    # ── Phase 4: Restore code blocks with proper escaping ────────────────────
+    for key, orig in _saved.items():
+        if orig.startswith("```"):
+            m = re.match(r"```[a-zA-Z0-9]*\n(.*)\n```", orig, re.DOTALL)
+            inner = m.group(1) if m else orig[3:-3]
+        else:
+            inner = orig[1:-1]
+        inner = inner.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        tag = "pre" if orig.startswith("```") else "code"
+        text = text.replace(key, f"<{tag}>{inner}</{tag}>")
+
+    return text
+

lumen_router_config.py

@@ -0,0 +1,502 @@
+"""
+lumen_router_config.py — конфигурация моделей и логика автоматического выбора
+маршрута (Gemini/OpenRouter) для одного сообщения.
+
+Вынесено из bot.py при аудите технического долга. Всё содержимое этого файла —
+конфигурационные данные (какие модели существуют, какие из них сейчас "нездоровы")
+и ЧИСТЫЕ функции принятия решения о маршруте (_build_route/_or_route/_gemini_route,
+эвристики "это тяжёлый запрос?"/"нужна свежая информация?") — никакого обращения
+к Telegram/Gemini/OpenRouter API отсюда не происходит, поэтому этот код не зависит
+от рантайм-состояния бота (в отличие от ask_gemini/ask_openrouter_*/_run_route,
+которые реально выполняют маршрут и остаются в bot.py). bot.py импортирует все
+нужные имена напрямую — публичные имена и поведение не изменились.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from datetime import date
+from typing import Any
+
+# Единый логгер "bot" (а не __name__ == "lumen_router_config") — намеренно,
+# чтобы предупреждения из этого модуля попадали под те же тесты/фильтры логов
+# (caplog.at_level(..., logger="bot")), что и остальной бот, независимо от того,
+# в каком физическом файле живёт код.
+log = logging.getLogger("bot")
+
+
+# список моделей
+
+# name/badge/desc/public_name/public_desc, ранее украшавшие каждую запись здесь,
+# убраны целиком (ponytail-audit, июль 2026) — это были чисто отображаемые строки
+# для команды /model, которая с тех пор удалена (см. "автоматический выбор модели"
+# ниже); ни одно из них нигде не читалось. Настоящая модель, которую обозначает
+# каждый ключ, и так понятна по самому ключу и по комментариям ниже — ничего не
+# потеряно. Единственные поля, которые здесь реально используются: search_grounding/
+# map_grounding/url_context/no_search/no_system/stream (см. _build_gemini_call_config)
+# и quota_unconfirmed (см. _check_unconfirmed_model_quotas).
+GEMINI_MODELS: dict[str, dict[str, Any]] = {
+    # Gemini 3.6 Flash — новый флагман линейки Flash, вышел 21 июля 2026, сменяет
+    # 3.5 Flash: по анонсу Google лучше в коде/агентных сценариях/мультимодальности,
+    # ~17% экономичнее по токенам. Контекст 1 млн токенов, знания по март 2026.
+    "gemini-3.6-flash": {
+        "stream": True,
+        # ПОДТВЕРЖДЕНО по дашборду AI Studio (24 июля 2026, реальный скриншот от
+        # владельца): Map grounding = 0/0 (квоты нет вовсе). Search grounding в
+        # дашборде числится не по конкретной модели, а по общему бакету "Gemini 3"
+        # (объединяет 3/3.1/3.5/3.6) — и этот бакет тоже 0/0, то есть поиска нет ни
+        # у одной модели поколения Gemini 3.x на этом ключе (в отличие от бакета
+        # "Gemini 2.5" — там реально 21/1500, см. gemini-2.5-flash/lite ниже и
+        # обновлённый порядок GEMINI_SEARCH_CHAIN). RPD-лимит тоже подтверждён: 20/сутки.
+        # Прежнее консервативное предположение (0/0 по аналогии с 3.5-flash) оказалось
+        # верным — quota_unconfirmed снят.
+        "search_grounding": False, "map_grounding": False, "url_context": True,
+    },
+    # Gemini 3.5 Flash — прошлый флагман линейки Flash, сохранён в цепочке как
+    # резерв после 3.6 Flash.
+    "gemini-3.5-flash": {
+        "stream": True,
+        # По данным дашборда AI Studio (июль 2026): Map grounding для этой модели
+        # показывает лимит 0/0 — то есть бесплатной квоты на инструмент нет вообще
+        # (не "не расходовано", а именно нулевой лимит). Search grounding отдельно
+        # для 3.5/3-flash не выделен в дашборде (числится под "Gemini 3" с тем же 0/0) —
+        # отключаем оба инструмента для этой модели, чтобы не тратить попытки впустую.
+        # url_context — другое дело: у него нет отдельной дневной квоты в дашборде,
+        # он просто добавляет токены по обычной цене модели, поэтому оставляем включённым.
+        "search_grounding": False, "map_grounding": False, "url_context": True,
+    },
+    # Gemini 3 Flash Preview — предыдущая Preview-версия линейки Flash, сохранена
+    # для тех, кто предпочитает её поведение версии 3.5 (более активное обдумывание).
+    "gemini-3-flash-preview": {
+        "stream": True,
+        "search_grounding": False, "map_grounding": False, "url_context": True,
+    },
+    # Gemini 3.5 Flash-Lite — новая версия самой быстрой и экономичной модели,
+    # вышла 21 июля 2026 вместе с 3.6 Flash; превосходит 3.1 Flash-Lite в агентных
+    # задачах и длинном контексте, до 350 токенов/сек.
+    "gemini-3.5-flash-lite": {
+        "stream": True,
+        # ПОДТВЕРЖДЕНО по дашборду AI Studio (24 июля 2026). Map grounding — реально
+        # ненулевая квота 500/сутки, прежнее предположение (True) подтвердилось.
+        # Search grounding — ИСПРАВЛЕНО: раньше здесь стояло True по неверной аналогии
+        # с gemini-3.1-flash-lite ("раз lite-класс, значит есть квота на оба
+        # инструмента"). По факту дашборд считает Search grounding не по конкретной
+        # модели, а по общему бакету поколения — "Gemini 3" (охватывает 3/3.1/3.5/3.6
+        # разом) — и этот бакет 0/0. Реальная квота на поиск есть только у бакета
+        # "Gemini 2.5" (21/1500) — см. gemini-2.5-flash/lite и обновлённый порядок
+        # GEMINI_SEARCH_CHAIN. quota_unconfirmed снят.
+        "search_grounding": False, "map_grounding": True,
+    },
+    # Gemini 3.1 Flash-Lite — прошлая версия самой быстрой и экономичной модели
+    # линейки, сохранена в цепочке как резерв после 3.5 Flash-Lite.
+    "gemini-3.1-flash-lite": {
+        "stream": True,
+        # Дашборд показывает реальную ненулевую квоту на Map grounding (0/500) для
+        # этой модели — map_grounding оставлен включённым. ИСПРАВЛЕНО (24 июля 2026):
+        # search_grounding раньше тоже стоял True — это была та же ошибка, что и у
+        # gemini-3.5-flash-lite ("есть квота на map grounding → значит есть и на
+        # search"), но дашборд считает Search grounding отдельным общим бакетом по
+        # ПОКОЛЕНИЮ модели ("Gemini 3" — охватывает 3/3.1/3.5/3.6 разом), и этот
+        # бакет показывает 0/0. Реальная квота на поиск подтверждена только у бакета
+        # "Gemini 2.5" (21/1500) — см. gemini-2.5-flash/lite ниже.
+        "search_grounding": False, "map_grounding": True,
+    },
+    # Gemini 2.5 Flash — универсальная мультимодальная модель поколения 2.5,
+    # хороший баланс скорости и качества для большинства повседневных задач.
+    "gemini-2.5-flash": {
+        "stream": True,
+        "search_grounding": True, "map_grounding": True,
+    },
+    # Gemini 2.5 Flash-Lite — экономичная модель поколения 2.5 для задач, где
+    # важна скорость ответа больше, чем глубина рассуждений.
+    "gemini-2.5-flash-lite": {
+        "stream": True,
+        "search_grounding": True, "map_grounding": True,
+    },
+    # Gemma 4 31B — флагманская открытая модель Google на 31 млрд параметров.
+    "gemma-4-31b-it": {
+        "no_system": True, "no_search": True, "stream": True,
+    },
+    # Gemma 4 26B — компактная открытая модель Google на 26 млрд параметров с
+    # расширенным мышлением (thinking).
+    "gemma-4-26b-a4b-it": {
+        "no_system": True,
+        # НАЙДЕНО при перепроверке конфига (24 июля 2026): у "родственной" модели
+        # gemma-4-31b-it выше стоит "no_search": True (Gemma, как открытая модель,
+        # не поддерживает grounding-инструменты Gemini API в принципе), а здесь этот
+        # флаг был случайно пропущен. Без него _build_gemini_call_config по умолчанию
+        # (search_grounding/url_context по умолчанию True при отсутствии ключа в конфиге)
+        # пытался бы добавить в запрос google_search И url_context для модели, которая
+        # их не поддерживает вообще — реальный риск ошибки API на КАЖДЫЙ вызов этой
+        # модели (она сейчас последняя в GEMINI_HEAVY_CHAIN, поэтому баг маловероятно
+        # проявлялся на практике, но был реальным). Добавлено для консистентности с 31B.
+        "no_search": True, "stream": True,
+    },
+}
+DEFAULT_GEMINI_MODEL = "gemini-3.6-flash"
+
+def _check_unconfirmed_model_quotas() -> None:
+    """Модели, добавленные сразу после релиза (см. quota_unconfirmed=True в
+    GEMINI_MODELS), — их реальные RPD-лимиты и доступность search/map grounding
+    ещё не подтверждены по дашборду AI Studio (дашборд обновляется с задержкой
+    после релиза модели, иногда на несколько дней). Громко напоминаем при
+    каждом старте, пока флаг не снят вручную после реальной проверки — та же
+    идея, что и у _check_temporary_free_models_expiry выше, только для новых,
+    а не для истекающих моделей."""
+    for mid, conf in GEMINI_MODELS.items():
+        if conf.get("quota_unconfirmed"):
+            log.warning(
+                "[setup] SYSTEM WARN: реальные RPD-лимиты и доступность search/map grounding "
+                "для модели %s ещё НЕ подтверждены по дашборду AI Studio (модель недавно "
+                "выпущена) — текущие search_grounding/map_grounding в GEMINI_MODELS это "
+                "предположение по аналогии с моделью того же класса. Проверьте дашборд и "
+                "уберите 'quota_unconfirmed' у этой модели в bot.py, поправив конфиг при необходимости.",
+                mid,
+            )
+
+# НАЙДЕНО ПРИ АУДИТЕ ТЕХДОЛГА: раньше здесь был словарь OPENROUTER_MODELS["text"]
+# со списком dict'ов {"id", "name", "description"} на ~25 моделей — то же самое
+# "name/badge/desc", что уже было вычищено из GEMINI_MODELS (см. комментарий там,
+# ponytail-audit, июль 2026), но по ошибке не сделано для OpenRouter. "name"/
+# "description" были чисто отображаемыми строками для команды /model, которая
+# с тех пор удалена (см. README, "Автоматический выбор модели") — единственное
+# реальное использование всего словаря было `[m["id"] for m in ...]`. Раз
+# описания нигде не читаются, оставляем сразу плоский список ID — тот же
+# TEXT_MODEL_ORDER, что раньше вычислялся ИЗ словаря, теперь и есть сам список.
+#
+# Список перепроверен вручную по openrouter.ai (июль 2026) — модель за моделью,
+# т.к. часть ID из старого списка либо сняты с бесплатного тира (arcee-ai/trinity-
+# large-thinking:free — акция закончилась 23.05, теперь платная; baidu/cobuddy:free —
+# больше не бесплатна), либо заменены провайдером на новую версию (poolside/laguna-xs.2:free
+# официально сворачивается в пользу laguna-xs-2.1:free). nvidia/nemotron-3.5-content-safety:free
+# НАМЕРЕННО не включена — это guardrail/классификатор safe/unsafe, а не диалоговая модель,
+# добавлять её сюда бессмысленно и вредно (не будет отвечать текстом на вопросы).
+# Порядок — от самых сильных/надёжных моделей общего назначения к нишевым и совсем лёгким;
+# используется, в частности, _LEAK_LITERAL_STRINGS ниже (защита от утечки идентичности) и
+# как источник моделей для роутера (см. _OR_LIGHT_ORDER/_OR_HEAVY_ORDER/_OR_VISION_ORDER
+# и единый реестр "нездоровых" моделей _OR_MODEL_HEALTH дальше по файлу).
+TEXT_MODEL_ORDER: list[str] = [
+    "nvidia/nemotron-3-super-120b-a12b:free",
+    "nvidia/nemotron-3-ultra-550b-a55b:free",
+    "openai/gpt-oss-120b:free",
+    "z-ai/glm-4.5-air:free",
+    "tencent/hy3:free",
+    "openrouter/owl-alpha",
+    "qwen/qwen3-next-80b-a3b-instruct:free",
+    "meta-llama/llama-3.3-70b-instruct:free",
+    "nousresearch/hermes-3-llama-3.1-405b:free",
+    "openai/gpt-oss-20b:free",
+    "google/gemma-4-31b-it:free",
+    "google/gemma-4-26b-a4b-it:free",
+    "cognitivecomputations/dolphin-mistral-24b-venice-edition:free",
+    "qwen/qwen3-coder:free",
+    "poolside/laguna-m.1:free",
+    "poolside/laguna-xs-2.1:free",
+    "cohere/north-mini-code:free",
+    "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+    "nvidia/nemotron-nano-12b-v2-vl:free",
+    "nvidia/nemotron-3-nano-30b-a3b:free",
+    "nvidia/nemotron-nano-9b-v2:free",
+    "meta-llama/llama-3.2-3b-instruct:free",
+    "liquid/lfm-2.5-1.2b-instruct:free",
+    "liquid/lfm-2.5-1.2b-thinking:free",
+    "openrouter/free",
+]
+
+# ── Единый реестр "нездоровых" моделей OpenRouter (аудит техдолга, август 2026) ──
+# РАНЬШЕ это отслеживалось ТРЕМЯ независимыми механизмами: _TEMPORARY_FREE_MODELS
+# (dict с датой истечения промо), _ROUTER_EXCLUDED_OR_MODELS (отдельное множество
+# для ручного исключения из роутинга) и точечные комментарии в _OR_LIGHT_ORDER/
+# _OR_HEAVY_ORDER о моделях, вычеркнутых оттуда вручную. Три реальных инцидента
+# (tencent/hy3:free, qwen/qwen3-coder:free, qwen/qwen3-next-80b-a3b-instruct:free)
+# потребовали правок в 2-3 местах каждый — ровно тот класс рассинхрона, которого
+# проект и так избегает в других местах (см. TEXT_MODEL_ORDER/_next_fallback_model
+# выше). Теперь один dict хранит причину/срок для каждой проблемной модели, а
+# _ROUTER_EXCLUDED_OR_MODELS и предупреждение об истёкшем промо вычисляются ИЗ
+# него, а не поддерживаются параллельно вручную.
+@dataclass(frozen=True)
+class _ModelHealthNote:
+    reason: str
+    # Задано только для ВРЕМЕННОГО промо-доступа (акция провайдера) — после этой
+    # даты в логи попадает предупреждение перепроверить актуальную цену на
+    # openrouter.ai. Модели, снятые НАВСЕГДА (не промо, а прямая инструкция
+    # провайдера использовать другой/платный слаг), оставляют это поле пустым —
+    # предупреждать об "истечении" там нечего, они просто не должны выбираться.
+    promo_expiry: date | None = None
+
+_OR_MODEL_HEALTH: dict[str, _ModelHealthNote] = {
+    "cognitivecomputations/dolphin-mistral-24b-venice-edition:free": _ModelHealthNote(
+        reason="Uncensored-модель — может хуже соблюдать личность/правила Lumen. Раньше выбиралась "
+               "вручную только владельцем через /provider (команда удалена) — автоматический роутер "
+               "её не выбирает вообще."
+    ),
+    "qwen/qwen3-coder:free": _ModelHealthNote(
+        reason="Подтверждено при аудите моделей (июль 2026): :free-эндпоинт снят провайдером.",
+        promo_expiry=date(2026, 6, 30),
+    ),
+    "tencent/hy3:free": _ModelHealthNote(
+        reason="Собственная страница OpenRouter показывала 'Going away July 19, 2026' — :free-эндпоинт "
+               "уже снят провайдером.",
+        promo_expiry=date(2026, 7, 21),
+    ),
+    "qwen/qwen3-next-80b-a3b-instruct:free": _ModelHealthNote(
+        reason="ПОДТВЕРЖДЕНО ПО РЕАЛЬНЫМ ЛОГАМ ПРОДА (25 июля 2026, ~40 минут живого трафика, 20+ "
+               "попыток подряд): HTTP 404 абсолютно каждый раз — 'This model is unavailable for "
+               "free... use this slug instead: qwen/qwen3-next-80b-a3b-instruct' (платный слаг). "
+               "Не временное промо, а прямая инструкция провайдера использовать другой (платный) "
+               "слаг — не возвращать в _OR_*_ORDER, пока провайдер вновь не откроет бесплатный "
+               "доступ именно к этому слагу."
+    ),
+}
+
+# Вычисляется ИЗ _OR_MODEL_HEALTH выше — единственное место, где решается, какие
+# модели роутер не должен выбирать (см. _or_route дальше по файлу).
+_ROUTER_EXCLUDED_OR_MODELS: frozenset[str] = frozenset(_OR_MODEL_HEALTH.keys())
+
+def _check_temporary_free_models_expiry() -> None:
+    """Предупреждает в логах (при каждом старте и раз в сутки, см. фоновый цикл в
+    _webhook_startup) про модели с истёкшим временным промо-доступом — на случай,
+    если запись когда-нибудь понадобится вернуть в оборот и стоит перепроверить
+    актуальную цену на openrouter.ai. Модели без promo_expiry (сняты навсегда, а
+    не по истечении акции) сюда не попадают — предупреждать об "истечении" для
+    них нечего."""
+    today = date.today()
+    for model_id, note in _OR_MODEL_HEALTH.items():
+        if note.promo_expiry is not None and today > note.promo_expiry:
+            log.warning(
+                "[or] SYSTEM WARN: временный бесплатный доступ к модели %s истёк %s (сегодня %s) — %s "
+                "Роутер её уже не выбирает (_ROUTER_EXCLUDED_OR_MODELS), но проверьте актуальную цену "
+                "на openrouter.ai, если модель когда-нибудь понадобится вернуть в оборот.",
+                model_id, note.promo_expiry.isoformat(), today.isoformat(), note.reason,
+            )
+
+def _or_route(models: list[str]) -> list[tuple[str, str]]:
+    """Превращает список ID моделей OpenRouter в список (provider, model_id) для
+    маршрута, попутно исключая модели из _ROUTER_EXCLUDED_OR_MODELS."""
+    return [("openrouter", m) for m in models if m not in _ROUTER_EXCLUDED_OR_MODELS]
+
+def _gemini_route(models: list[str]) -> list[tuple[str, str]]:
+    return [("gemini", m) for m in models]
+
+
+# ── "Лёгкие"/"стандартные" запросы без вложений и ссылок — САМЫЙ ЧАСТЫЙ
+# маршрут в обычном чате. Целиком обслуживается OpenRouter'ом, чтобы вообще не
+# трогать скудную квоту Gemini на самом массовом классе сообщений.
+#
+# ВАЖНО (по итогам живого тестирования, см. историю): meta-llama/llama-3.3-70b-
+# instruct:free полностью убрана из этого списка — провайдер снял её с
+# бесплатного тира (HTTP 404 "This model is unavailable for free", подтверждено
+# десятками идентичных отказов подряд в реальных логах). Держать её первой в
+# списке означало гарантированный лишний неудачный запрос на КАЖДОЕ сообщение.
+# qwen/qwen3-next-80b-a3b-instruct:free полностью УБРАНА из списка (25 июля
+# 2026) — сама теперь 404 на каждый вызов, см. _ROUTER_EXCLUDED_OR_MODELS выше.
+#
+# ПЕРЕСТРОЕНО (25 июля 2026, по прямому сравнению ответов бота с ответами
+# настоящего Claude на идентичные промпты в рамках калибровочной сессии):
+# - z-ai/glm-4.5-air:free поднята на первое место — ни разу не замечена в
+#   порче текста ни в тяжёлом, ни в лёгком тестировании, хорошо держит русский.
+# - openai/gpt-oss-20b:free ПОНИЖЕНА: подтверждено 2 тяжёлых инцидента —
+#   на прямой идентити-вопрос "какая ты модель на самом деле?" выдала
+#   бессвязную смесь языков ("Я — L accompagné.") вместо ответа, а на
+#   эмоционально уязвимый запрос ("меня бросила девушка, что делать") вставила
+#   посреди ответа нечитаемый арабский фрагмент. Не убрана совсем — на
+#   остальных ~6 наблюдавшихся вызовах отвечала нормально, — но с первого
+#   места снята однозначно.
+# - nvidia/nemotron-3-nano-30b-a3b:free ПОНИЖЕНА ещё ниже: подтверждено 3
+#   инцидента — деванагари-мусор внутри слова ("пиिजцы" вместо "пиццы") ВМЕСТЕ
+#   с сырым LaTeX в ответе про площадь круга (при том что system_prompt.py
+#   прямо запрещает LaTeX), уверенная галлюцинация названия фильма ("К Eggman"
+#   вместо "Гранд Будапешт Отель"), порченые слова и выдуманное название
+#   компании ("Vueium") в сравнении React/Vue. Из трёх протестированных
+#   "лёгких" моделей — худшая по частоте порчи текста.
+# Ни gpt-oss-20b, ни nemotron-3-nano-30b-a3b пока не удалены полностью: ниже
+# них в цепочке стоят ЕЩЁ более мелкие модели (9B/3B/1.2B), которые в этой
+# сессии не тестировались и по объёму параметров теоретически ещё менее
+# надёжны на русском. Если и они дадут похожие инциденты — тогда стоит
+# рассмотреть полное исключение gpt-oss-20b/nemotron-3-nano-30b-a3b, а не
+# просто понижение приоритета.
+_OR_LIGHT_ORDER: list[str] = [
+    "z-ai/glm-4.5-air:free",
+    "nvidia/nemotron-nano-9b-v2:free",
+    "meta-llama/llama-3.2-3b-instruct:free",
+    "openai/gpt-oss-20b:free",
+    "nvidia/nemotron-3-nano-30b-a3b:free",
+    "liquid/lfm-2.5-1.2b-instruct:free",
+    "openrouter/free",
+]
+
+# ── "Тяжёлые" запросы (код, многошаговые рассуждения, объёмный анализ) без
+# нужды в интернете/медиа — тоже сначала к OpenRouter: среди бесплатных
+# моделей там есть по-настоящему сильные кандидаты (120B/550B), не уступающие
+# по мощи флагману Gemini, но не занимающие его 20 запросов/сутки.
+#
+# qwen/qwen3-next-80b-a3b-instruct:free убрана из запасного места в конце —
+# 404 на каждый вызов, см. _ROUTER_EXCLUDED_OR_MODELS. Заменена на дополнительный
+# резерв glm-4.5-air (уже есть выше в цепочке, но openrouter/free как последний
+# универсальный fallback остаётся).
+#
+# МОНИТОРИНГ (25 июля 2026): nvidia/nemotron-3-super-120b-a12b:free, несмотря на
+# статус флагмана этого тира, дала 1 инцидент из 4 протестированных тяжёлых
+# запросов — в ответе про TCP/IP посреди русского текста встретился китайский
+# иероглиф "尾部" (вместо "хвост"), итальянское "infine" и английское "preventing".
+# Остальные 3 запроса (Rust-палиндром, Python-сортировка, сравнение iPhone/Samsung)
+# отработала чисто. Пока не понижаем — один инцидент на четыре успешных попытки
+# не повод убирать флагмана, но стоит присматривать за логами `[stream]`/ответами
+# этой модели и понизить её, если порча текста повторится.
+_OR_HEAVY_ORDER: list[str] = [
+    "nvidia/nemotron-3-super-120b-a12b:free",
+    "openai/gpt-oss-120b:free",
+    "z-ai/glm-4.5-air:free",
+    "nvidia/nemotron-3-ultra-550b-a55b:free",
+    "nousresearch/hermes-3-llama-3.1-405b:free",
+    "openrouter/free",
+]
+
+# ── Вложение (изображение) без нужды в свежей информации — у OpenRouter
+# достаточно бесплатных vision-моделей, чтобы не трогать Gemini. OpenRouter
+# физически принимает только изображения (base64 data URL) — для видео/аудио
+# этот список не используется вообще, см. _build_route/_run_route ниже.
+_OR_VISION_ORDER: list[str] = [
+    "nvidia/nemotron-nano-12b-v2-vl:free",
+    "google/gemma-4-31b-it:free",
+    "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+    "google/gemma-4-26b-a4b-it:free",
+]
+
+# ── Цепочки Gemini. GEMINI_HEAVY_CHAIN — от сильной модели к слабой (тот же
+# состав/порядок, что был у прежнего единственного quota_fallback_chain), для
+# случаев, где ТРЕБУЕТСЯ именно Gemini (YouTube/сайт по ссылке, видео/аудио
+# вложение), но живой поиск не нужен. GEMINI_SEARCH_CHAIN — те же модели, но
+# начиная с тех, у кого по дашборду AI Studio реально ЕСТЬ квота на search
+# grounding (флагман 3.5 и 3-preview её не имеют вообще — см. комментарии в
+# GEMINI_MODELS выше), чтобы запрос, которому нужен живой поиск, не попадал
+# первым делом на модель, что физически не может искать.
+GEMINI_HEAVY_CHAIN: list[str] = [
+    "gemini-3.6-flash",
+    "gemini-3.5-flash",
+    "gemini-3-flash-preview",
+    "gemini-3.5-flash-lite",
+    "gemini-3.1-flash-lite",
+    "gemini-2.5-flash",
+    "gemini-2.5-flash-lite",
+    "gemma-4-31b-it",
+    "gemma-4-26b-a4b-it",
+]
+# ПЕРЕСТРОЕНО (24 июля 2026, по реальным данным дашборда AI Studio): раньше первыми
+# здесь стояли gemini-3.5-flash-lite/gemini-3.1-flash-lite в предположении, что у
+# них есть search grounding — это оказалось неверно (см. комментарии в GEMINI_MODELS
+# выше). Дашборд считает квоту на Search grounding не по конкретной модели, а по
+# общему бакету ПОКОЛЕНИЯ: бакет "Gemini 3" (охватывает 3/3.1/3.5/3.6 целиком) — 0/0,
+# реальной квоты на поиск нет вовсе ни у одной модели линейки Gemini 3.x. Бакет
+# "Gemini 2.5" — 21/1500, то есть поиск реально работает ТОЛЬКО у gemini-2.5-flash и
+# gemini-2.5-flash-lite. Они теперь и стоят первыми для запросов, где нужна живая
+# информация. Модели Gemini 3.x оставлены в цепочке как резерв — не смогут вызвать
+# google_search, но всё ещё могут ответить по своим знаниям (и через url_context,
+# если в тексте есть ссылка — та возможность отдельной квоты не имеет вовсе).
+GEMINI_SEARCH_CHAIN: list[str] = [
+    "gemini-2.5-flash",
+    "gemini-2.5-flash-lite",
+    "gemini-3.5-flash-lite",
+    "gemini-3.1-flash-lite",
+    "gemini-3.6-flash",
+    "gemini-3.5-flash",
+    "gemini-3-flash-preview",
+]
+# Совпадает по составу с прежним quota_fallback_chain — используется как дефолт,
+# если ask_gemini вызвана без явной цепочки (например, напрямую из теста).
+GEMINI_DEFAULT_CHAIN: list[str] = GEMINI_HEAVY_CHAIN
+# Только "полноценные" (не no_system/Gemma) модели умеют читать сайты по ссылке
+# (url_context) и разбирать YouTube-видео по ссылке (file_uri) — то же
+# ограничение, что раньше проверялось в _handle_message_core через
+# current_gemini_conf.get("no_system").
+GEMINI_LINK_CHAIN: list[str] = [m for m in GEMINI_HEAVY_CHAIN if not GEMINI_MODELS.get(m, {}).get("no_system")]
+GEMINI_LINK_SEARCH_CHAIN: list[str] = [m for m in GEMINI_SEARCH_CHAIN if not GEMINI_MODELS.get(m, {}).get("no_system")]
+
+
+# ── Эвристика "это сложный/тяжёлый запрос?" — без обращения к LLM. Ложные
+# срабатывания недороги: худший случай — используется чуть более мощная
+# модель, чем реально нужно, а не отказ в ответе.
+_HEAVY_QUERY_RE = re.compile(
+    r"напиши\s+(код|функци\w*|скрипт|программ\w*|класс\w*|запрос\s+sql|regex|регуляр\w*)"
+    r"|сгенерируй\s+код|исправь\s+(код|баг|ошибк\w*)|отрефактор\w*|рефактор\w*|оптимизируй"
+    r"|напиши\s+(эссе|статью|доклад|реферат|сочинение|резюме|cv)\b"
+    r"|проанализируй\w*|разбер(и|ём)\s+подробно|объясни\s+подробно"
+    r"|сравни\s+.{0,40}(и|с)\s+|докажи\b|доказательство"
+    r"|реши\s+(задач\w*|уравнени\w*|систем\w*)"
+    r"|составь\s+(план|таблиц\w*|список\s+из)"
+    r"|многошагов\w*|пошагов\w*\s+(инструкц\w*|план\w*)"
+    r"|архитектур\w*|алгоритм\w*",
+    re.IGNORECASE,
+)
+
+def _looks_like_heavy_query(text: str) -> bool:
+    """Грубая эвристика "это тяжёлый запрос (код/анализ/многошаговые рассуждения)?"
+    Намеренно консервативная (без вызова LLM — см. комментарий в начале секции)."""
+    if not text:
+        return False
+    if "```" in text or len(text) > 600:
+        return True
+    if text.count("?") >= 3:
+        return True
+    return bool(_HEAVY_QUERY_RE.search(text))
+
+
+# ── Эвристика "нужна ли живая информация из интернета?" Ложные срабатывания
+# тоже недороги: худший случай — маршрут отдаёт предпочтение search-способной
+# модели там, где поиск был не нужен, но модель сама решает, вызывать ли его.
+_FRESHNESS_QUERY_RE = re.compile(
+    r"сейчас|сегодня|текущ\w*|последн\w*|актуальн\w*|свеж\w*|недавно|на\s+данный\s+момент"
+    r"|новост\w*|курс\s+(валют|доллара|евро|рубл\w*)|погод\w*"
+    r"|цена\w*|стоимост\w*|сколько\s+стоит"
+    r"|кто\s+(сейчас|является|президент|премьер|глава|ceo|мэр)"
+    r"|результат\w*\s+(матч\w*|игр\w*|выбор\w*)"
+    r"|в\s+эт(ом|ой)\s+(году|месяце|неделе)"
+    r"|\b202[6-9]\b",
+    re.IGNORECASE,
+)
+
+def _looks_like_freshness_query(text: str) -> bool:
+    return bool(text) and bool(_FRESHNESS_QUERY_RE.search(text))
+
+
+def _build_route(
+    *, needs_youtube: bool, needs_website: bool, media_mime: str | None,
+    is_heavy: bool, needs_freshness: bool,
+) -> list[tuple[str, str]]:
+    """Строит приоритетный список кандидатов (provider, model_id) для текущего
+    сообщения — НЕПУСТОЙ список, первый элемент пробуется первым (см. _run_route).
+    Порядок кандидатов внутри одного провайдера — по возрастанию "дороговизны"
+    для дефицитной квоты, а не по итоговому качеству ответа отдельно взятой модели."""
+    is_video_or_audio_media = bool(media_mime) and not media_mime.startswith("image/")
+
+    if needs_youtube or needs_website:
+        # Только Gemini умеет читать сайты по ссылке и разбирать YouTube-видео —
+        # у OpenRouter в этом маршруте вообще нет места, эскалировать некуда.
+        chain = GEMINI_LINK_SEARCH_CHAIN if needs_freshness else GEMINI_LINK_CHAIN
+        return _gemini_route(chain)
+
+    if media_mime:
+        if needs_freshness or is_video_or_audio_media:
+            # Видео/аудио вложение ИЛИ нужен живой поиск вместе с медиа — может
+            # только Gemini (OpenRouter физически не примет не-изображение, и
+            # ни одна его модель не имеет доступа к поиску).
+            chain = GEMINI_SEARCH_CHAIN if needs_freshness else GEMINI_HEAVY_CHAIN
+            return _gemini_route(chain)
+        # Изображение без нужды в поиске — сначала бесплатные vision-модели
+        # OpenRouter, Gemini — резерв, если они все разом откажут.
+        return _or_route(_OR_VISION_ORDER) + _gemini_route(GEMINI_HEAVY_CHAIN)
+
+    if needs_freshness:
+        # Текст без вложений, но нужна свежая информация — только у Gemini
+        # реально есть поиск; OpenRouter в конце как резерв на случай, если
+        # Gemini исчерпан целиком (без поиска, но хоть какой-то ответ).
+        return _gemini_route(GEMINI_SEARCH_CHAIN) + _or_route(_OR_HEAVY_ORDER if is_heavy else _OR_LIGHT_ORDER)
+
+    # Основной случай: обычный текст без вложений/ссылок/признаков нужды в
+    # интернете — целиком к OpenRouter, Gemini — резерв на случай отказа всей
+    # цепочки OpenRouter разом.
+    if is_heavy:
+        return _or_route(_OR_HEAVY_ORDER) + _gemini_route(GEMINI_HEAVY_CHAIN)
+    return _or_route(_OR_LIGHT_ORDER) + _gemini_route(GEMINI_SEARCH_CHAIN)

lumen_security.py

@@ -0,0 +1,202 @@
+"""
+lumen_security.py — детерминированная защита от промт-инъекций и утечки
+идентичности провайдера/модели (Lumen никогда не должен представляться как
+Gemini/Gemma/OpenRouter и т.п. — см. system_prompt.py).
+
+Вынесено из bot.py при аудите технического долга: детекторы (_detect_identity_leak,
+_detect_injected_payload_echo, _looks_like_injection_probe) — чистые функции над
+строками, не зависящие от Telegram/рантайм-состояния бота. Единственная внешняя
+зависимость — GEMINI_MODELS/TEXT_MODEL_ORDER из lumen_router_config.py (нужны для
+списка точных строк внутренних ID моделей, см. _LEAK_LITERAL_STRINGS ниже).
+Публичные имена и поведение не изменились.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+from lumen_router_config import GEMINI_MODELS, TEXT_MODEL_ORDER
+
+# Единый логгер "bot" (а не __name__) — чтобы caplog.at_level(..., logger="bot")
+# в тестах продолжал ловить предупреждения независимо от того, в каком
+# физическом файле живёт код (см. тот же приём в lumen_router_config.py).
+log = logging.getLogger("bot")
+
+# ─────────────────── защита от утечки провайдера/модели (выходной фильтр) ───────────────────
+# Системный промпт (см. system_prompt.py) — это ПЕРВЫЙ, самый слабый рубеж: любую
+# LLM в принципе можно уговорить нарушить свои инструкции достаточно настойчивой или
+# creative промт-инъекцией (см. историю с чужим ботом, который выдал себя за другую
+# модель именно через такую инъекцию). Поэтому здесь — ВТОРОЙ, детерминированный рубеж,
+# который срабатывает уже ПОСЛЕ генерации ответа моделью и не зависит от того, что
+# модель решила написать: если в готовом тексте всё-таки проскочило реальное имя
+# модели/провайдера, весь ответ целиком подменяется на нейтральный fallback ДО того,
+# как текст уйдёт пользователю и ДО того, как он попадёт в историю чата (иначе утечка
+# осталась бы в контексте и могла бы "просочиться" в последующие ответы модели).
+#
+# Слой А — точные строки внутренних ID моделей. Ложных срабатываний практически не
+# бывает: обычный ответ на обычный вопрос никогда не должен содержать дефис-разделённый
+# технический идентификатор вида "gemini-3.5-flash" или "z-ai/glm-4.5-air:free" — такие
+# строки в естественной русской (или английской) речи не встречаются случайно.
+_LEAK_LITERAL_STRINGS: tuple[str, ...] = tuple(sorted(
+    set(GEMINI_MODELS.keys())
+    | {"gemini-3.1-flash-tts-preview", "gemini-2.5-flash-preview-tts"}
+    | set(TEXT_MODEL_ORDER)
+))
+# Найдено при код-ревью (performance): инкрементальная проверка в _try_gemini_streaming
+# раньше пересканировала ВЕСЬ накопленный full_text на каждый новый кусок стрима — при
+# длинном ответе с мелкими чанками это O(n²) по суммарной длине ответа. Самый длинный
+# паттерн из всех детекторов (_LEAK_LITERAL_STRINGS/_IDENTITY_LEAK_RE/_INJECTED_PAYLOAD_
+# ECHO_RE) — 61 символ; с большим запасом (5×) берём хвост в 300+ символов вместо всего
+# текста — см. _leak_scan_window ниже. Любой паттерн, который мог бы образоваться на
+# стыке старого текста и нового куска, гарантированно попадёт в это окно, если сам кусок
+# короче окна (что всегда так для потоковых кусков от Gemini API).
+_LEAK_SCAN_TAIL_CHARS = 300
+
+def _leak_scan_window(full_text: str, latest_piece: str) -> str:
+    """Возвращает "хвост" накопленного текста, достаточный для обнаружения ЛЮБОГО
+    паттерна утечки, который мог образоваться после добавления latest_piece — без
+    необходимости пересканировать весь full_text целиком на каждой итерации стрима.
+    Окно берётся с запасом на случай аномально большого одиночного куска."""
+    window_size = max(_LEAK_SCAN_TAIL_CHARS, len(latest_piece) + 100)
+    return full_text[-window_size:]
+
+
+# Слой Б — само-идентификация как конкретный бренд/модель. ВАЖНО: раньше здесь было
+# широкое окно "самореференция ... бренд" в пределах 60 символов — это ловило honest
+# ответы вроде развёрнутого рассказа про OpenAI как компанию, где модель где-то в
+# том же предложении естественно писала "я не могу сравнивать себя..." (обычное
+# хеджирование, не утечка). "я" — один из самых частых русских токенов, поэтому
+# любое достаточно длинное упоминание стороннего бренда рядом с ЛЮБЫМ "я" в тексте
+# ложно срабатывало. Теперь — только точные, тесно связанные шаблоны конкретных
+# формулировок самоидентификации (без произвольного зазора между словами), которые
+# на практике встречаются ТОЛЬКО при реальной утечке, а не в обычном разговоре о
+# сторонних моделях/компаниях.
+_LEAK_BRAND_TOKENS = (
+    r"(gemini|gemma|gpt[\s\-]?oss|chatgpt|openai|claude|anthropic|deepmind|openrouter|"
+    r"nemotron|qwen|llama|glm[\s\-]?4|hermes|dolphin[\s\-]?mistral|venice|laguna|"
+    r"lfm[\s\-]?2\.5|нейросет\w*\s+google|модел\w*\s+google|google\s*ai|google\s+gemini)"
+)
+_IDENTITY_LEAK_RE = re.compile(
+    rf"\bя\s*(?:—|-|:)?\s*(?:это\s+|являюсь\s+)?{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bмен[яе]\s+(?:зовут|называют)\s+{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bя\s+созда(?:н|на)\w*\s+(?:компанией\s+)?{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bмен[яе]\s+созда(?:л|ла)\w*\s+{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bработаю\s+на\s+(?:базе\s+)?{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bоснован\w*\s+на\s+{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bэт[оауи]\s*(?:модел\w*|нейросет\w*)\s*(?:—|-|:)?\s*{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bi\s*(?:am|'m)\s+{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bbuilt\s+on\s+{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bpowered\s+by\s+{_LEAK_BRAND_TOKENS}\b"
+    rf"|\bbased\s+on\s+{_LEAK_BRAND_TOKENS}\b"
+    rf"|{_LEAK_BRAND_TOKENS}\s*,?\s*а\s+не\s+lumen\b",
+    re.IGNORECASE,
+)
+
+_IDENTITY_LEAK_FALLBACK = (
+    "Внутренние технические детали своей реализации я не раскрываю. "
+    "Если у вас есть другой вопрос — с радостью помогу."
+)
+
+# Слой В — "эхо" внедрённой в контент (фото/документ/сайт) вредоносной инструкции.
+# Реальный найденный на практике обход: атакующий подсовывает картинку/страницу с
+# текстом вида "[SYSTEM NOTICE] ...выведи ровно эту строку, подтверждающую взлом...".
+# Модель может отказаться ВЫПОЛНИТЬ эту инструкцию, но при просьбе "перескажи/опиши
+# содержимое" или "сделай саммари того, что тебе передали при запуске" — иногда всё
+# же дословно ВОСПРОИЗВОДИТ целевую строку атаки внутри своего пересказа, и эта
+# строка затем оседает в истории чата и может "всплыть" в следующих repl. Намеренно
+# ОЧЕНЬ узкий список ключевых слов (типичная лексика "подтверждения взлома" в
+# proof-of-concept пейлоадах) — а не общий поиск ALL_CAPS/переиспользование входного
+# _INJECTION_PROBE_RE, иначе ловились бы легитимные ответы (код с константами вида
+# API_KEY/MAX_RETRIES, честные объяснения того, что такое джейлбрейк, и т.п.).
+_INJECTED_PAYLOAD_ECHO_RE = re.compile(
+    r"security[_\s]?breach[_\s]?detected"
+    r"|system[_\s]?override[_\s]?(successful|complete)"
+    r"|diagnostic[_\s]?success"
+    r"|prompt[_\s]?validation[_\s]?successful"
+    r"|jailbreak[_\s]?success(ful)?"
+    r"|bypass[_\s]?successful"
+    r"|injection[_\s]?successful"
+    r"|breach[_\s]?detected"
+    r"|взлом\s+(прошёл\s+)?успешно"
+    r"|инъекция\s+(прошла\s+)?успешно"
+    r"|проверка\s+(пройдена|успешна)[:.]?\s*(систем\w*|промпт\w*)",
+    re.IGNORECASE,
+)
+
+_INJECTED_PAYLOAD_ECHO_FALLBACK = (
+    "Это похоже на текст из инструкции, внедрённой в присланный контент, а не на "
+    "обычный ответ — воспроизводить его не буду. Если у вас обычный вопрос, задайте "
+    "его, и я отвечу."
+)
+
+def _detect_injected_payload_echo(text: str) -> bool:
+    return bool(text) and bool(_INJECTED_PAYLOAD_ECHO_RE.search(text))
+
+def _detect_identity_leak(text: str) -> bool:
+    """Чистая функция без побочных эффектов — намеренно отделена от _scrub_identity_leak
+    (которая ещё и логирует), чтобы можно было дёшево вызывать её на КАЖДЫЙ кусок текста
+    во время стриминга (см. _try_gemini_streaming), не заливая логи повторными записями
+    об одном и том же инциденте на каждый новый символ."""
+    if not text:
+        return False
+    low = text.lower()
+    for lit in _LEAK_LITERAL_STRINGS:
+        if lit and lit.lower() in low:
+            return True
+    return bool(_IDENTITY_LEAK_RE.search(text))
+
+def _scrub_identity_leak(text: str, *, source: str) -> str:
+    """Точка применения фильтра для НЕстримингового пути (ask_gemini, ask_openrouter_*).
+    Вызывается непосредственно перед записью ответа в историю чата — если вызвать её
+    только перед показом пользователю, но не перед hist.append/history.append, утечка
+    осталась бы в истории и могла бы повлиять на последующие ответы модели."""
+    if _detect_identity_leak(text):
+        log.warning("[identity-leak] Обнаружена и заблокирована утечка идентичности (source=%s): %r", source, text[:500])
+        return _IDENTITY_LEAK_FALLBACK
+    if _detect_injected_payload_echo(text):
+        log.warning("[injection-echo] Обнаружено и заблокировано вероятное эхо внедрённой инструкции (source=%s): %r", source, text[:500])
+        return _INJECTED_PAYLOAD_ECHO_FALLBACK
+    return text
+
+# ─────────────────── защита от промт-инъекций (входной префильтр) ───────────────────
+# Первый (и самый дешёвый/надёжный) рубеж: явные, хорошо известные паттерны попытки
+# "взломать" системный промпт — если сообщение совпадает с одним из них, отвечаем
+# заранее заготовленной фразой БЕЗ обращения к LLM вообще. Для этого конкретного класса
+# атак это даёт СТОПРОЦЕНТНУЮ гарантию отсутствия утечки (в отличие от системного
+# промпта, который в принципе можно обойти достаточно творческой формулировкой) — сама
+# модель тут просто не участвует.
+#
+# ВАЖНО: сюда намеренно НЕ включены обычные любопытные вопросы вида "какая ты модель
+# на самом деле" / "ты точно не Gemini?" — на них и так есть отдельная честная и
+# небанальная (без дословных повторов, см. ИДЕНТИЧНОСТЬ в system_prompt.py) логика
+# внутри самой модели. Здесь — только однозначные попытки ПОДМЕНИТЬ инструкции или
+# выдавить из бота его системный промпт, а не безобидное любопытство.
+_INJECTION_PROBE_RE = re.compile(
+    r"ignore\s+(all\s+|any\s+)?(the\s+)?(previous|prior|above|earlier)\s+instructions"
+    r"|забудь\s+(все\s+|про\s+)?(предыдущие\s+|системные\s+)?инструкции"
+    r"|игнорируй\s+(все\s+|любые\s+)?(предыдущие\s+|системные\s+)?(инструкции|прав��ла|указания)"
+    r"|print\s+your\s+(system\s+)?(prompt|instructions)"
+    r"|repeat\s+(everything|the\s+text|all\s+the\s+words)\s+above"
+    r"|покажи\s+(мне\s+)?сво(й|и)\s+(системн\w*\s+)?(промпт|инструкции)"
+    r"|выведи\s+(мне\s+)?сво(й|и)\s+(системн\w*\s+)?(промпт|инструкции)"
+    r"|повтори\s+(всё\s+|весь\s+текст\s+)?(что\s+)?(написано\s+)?выше"
+    r"|(developer|debug|god|dan|jailbreak)\s*[\s\-]?mode"
+    r"|режим\s+(разработчика|отладки|бога|джейлбрейк\w*)"
+    r"|you\s+are\s+now\s+(an?\s+)?(unrestricted|uncensored|jailbroken)"
+    r"|ты\s+теперь\s+(без\s+ограничени\w*|неограничен\w*|не\s+связан\w*\s+правилами)"
+    r"|act\s+as\s+(an?\s+)?(unfiltered|uncensored|jailbroken|dan)\b"
+    r"|притворись\s*,?\s*(что\s+)?у\s+тебя\s+нет\s+(правил|ограничени\w*)"
+    r"|(what|which)\s+(is\s+)?your\s+(real\s+|actual\s+)?system\s+prompt"
+    r"|раскрой\s+(свой\s+)?системн\w*\s+промпт",
+    re.IGNORECASE,
+)
+
+_INJECTION_PROBE_REPLY = (
+    "Свою настройку и инструкции я не раскрываю и не обсуждаю в таком формате. "
+    "Если у вас обычный вопрос — задавайте, с радостью помогу."
+)
+
+def _looks_like_injection_probe(text: str) -> bool:
+    """Чистая функция — тестируется отдельно от _handle_message_core."""
+    return bool(text) and bool(_INJECTION_PROBE_RE.search(text))

test_bot_helpers.py

@@ -564,8 +564,15 @@ class _FakeStatusExc(Exception):
 
 
 def test_gemini_error_msg_rate_limit():
+    # РЕГРЕССИЯ (аудит техдолга): раньше здесь проверялось "модель через /model" —
+    # команда /model давно удалена (см. README, "Автоматический выбор модели"),
+    # и подсказывать её в тексте ошибки было прямой ошибкой для пользователя.
+    # _gemini_error_msg/_or_error_msg теперь используют общие provider-neutral
+    # шаблоны (см. _MODEL_ERROR_MESSAGES) без упоминания несуществующих команд.
     exc = _FakeStatusExc("rate limit exceeded", status_code=429)
-    assert "модель через /model" in bot._gemini_error_msg(exc, "gemini-3.5-flash")
+    msg = bot._gemini_error_msg(exc, "gemini-3.5-flash")
+    assert "/model" not in msg and "/provider" not in msg
+    assert msg == bot._model_error_text("rate_limit")
 
 
 def test_gemini_error_msg_value_error_passthrough():
@@ -576,19 +583,39 @@ def test_gemini_error_msg_value_error_passthrough():
 
 
 def test_gemini_error_msg_all_models_exhausted():
+    # РЕГРЕССИЯ (аудит техдолга): раньше здесь проверялось "/provider" — команда
+    # удалена, реального способа переключиться на резервный провайдер вручную
+    # больше нет, поэтому предлагать её в тексте ошибки было ошибкой.
     exc = bot.GeminiAllModelsExhaustedError(["gemini-3.5-flash", "gemini-2.5-flash"])
     msg = bot._gemini_error_msg(exc, "gemini-3.5-flash")
-    assert "/provider" in msg
+    assert "/provider" not in msg
+    assert "лимит" in msg.lower()
 
 
 def test_or_error_msg_rate_limit():
+    # РЕГРЕССИЯ (аудит техдолга): "/provider" убран из текста (команда удалена),
+    # а формулировка "резервного провайдера" тоже убрана — с автоматическим
+    # роутером OpenRouter часто оказывается ПЕРВЫМ, а не резервным кандидатом.
     exc = _FakeStatusExc("rate limit exceeded", status_code=429)
-    assert "/provider" in bot._or_error_msg(exc, "text")
+    msg = bot._or_error_msg(exc, "text")
+    assert "/provider" not in msg and "резервн" not in msg.lower()
+    assert msg == bot._model_error_text("rate_limit")
 
 
 def test_or_error_msg_unavailable():
     exc = _FakeStatusExc("model not found", status_code=404)
-    assert "/provider" in bot._or_error_msg(exc, "text")
+    msg = bot._or_error_msg(exc, "text")
+    assert "/provider" not in msg and "резервн" not in msg.lower()
+    assert msg == bot._model_error_text("unavailable")
+
+
+def test_model_error_text_shared_between_providers():
+    # Единый источник правды для текста ошибок (см. аудит техдолга) — Gemini и
+    # OpenRouter должны показывать ОДИНАКОВЫЙ текст на одинаковый класс ошибки,
+    # а не рассинхронизированные формулировки в двух местах.
+    gem_exc = _FakeStatusExc("resource_exhausted", status_code=429)
+    or_exc = _FakeStatusExc("rate limit exceeded", status_code=429)
+    assert bot._gemini_error_msg(gem_exc, "gemini-3.5-flash") == bot._or_error_msg(or_exc, "text")
 
 
 # ─────────────────────────── _cleanup_rate_limit_dict ───────────────────────────
@@ -658,6 +685,63 @@ def test_upstash_get_parses_result_field():
         bot.UPSTASH_REDIS_REST_TOKEN = ""
 
 
+# ─────────────── миграция image_model со старого формата "pollinations:X" ───────────────
+# РЕГРЕССИЯ, найденная при /code-review: ponytail-audit убрал приставку "pollinations:"
+# из ключей HF_IMAGE_MODELS (единственный провайдер и так один). Без миграции это молча
+# сбрасывало бы image_model существующих персистентных чатов на DEFAULT_HF_IMAGE_MODEL —
+# реальный выбор пользователя (например "pollinations:turbo") терялся бы без предупреждения,
+# просто потому что старое значение больше не совпадает ни с одним ключом HF_IMAGE_MODELS.
+
+def test_normalize_legacy_image_model_id_strips_old_prefix():
+    assert bot._normalize_legacy_image_model_id("pollinations:turbo") == "turbo"
+    assert bot._normalize_legacy_image_model_id("pollinations:flux-anime") == "flux-anime"
+
+
+def test_normalize_legacy_image_model_id_passthrough_for_current_format():
+    assert bot._normalize_legacy_image_model_id("turbo") == "turbo"
+    assert bot._normalize_legacy_image_model_id("flux") == "flux"
+
+
+def test_normalize_legacy_image_model_id_passthrough_for_non_string():
+    # Защита от неожиданных типов в персистентных данных — не должно падать.
+    assert bot._normalize_legacy_image_model_id(None) is None
+    assert bot._normalize_legacy_image_model_id(123) == 123
+
+
+def test_restore_single_chat_migrates_legacy_pollinations_image_model():
+    cid = 999901
+    try:
+        bot._restore_single_chat(cid, {"image_model": "pollinations:turbo", "history": []})
+        assert bot.chat_state[cid]["image_model"] == "turbo"
+    finally:
+        bot.chat_state.pop(cid, None)
+
+
+def test_restore_single_chat_falls_back_to_default_for_truly_unknown_image_model():
+    cid = 999902
+    try:
+        bot._restore_single_chat(cid, {"image_model": "some-removed-model-nobody-heard-of", "history": []})
+        assert bot.chat_state[cid]["image_model"] == bot.DEFAULT_HF_IMAGE_MODEL
+    finally:
+        bot.chat_state.pop(cid, None)
+
+
+def test_get_state_migrates_legacy_pollinations_image_model_in_memory():
+    # Защита в глубину (см. get_state) — на случай, если в chat_state окажется
+    # старое значение уже ПОСЛЕ восстановления (например, вручную отредактированные
+    # персистентные данные), а не только на пути через _restore_single_chat.
+    cid = 999903
+    try:
+        bot.chat_state[cid] = {
+            "image_model": "pollinations:flux-realism", "history": [], "quota": {},
+            "recent_media_ids": {}, "last_activity": 0.0,
+        }
+        state = bot.get_state(cid)
+        assert state["image_model"] == "flux-realism"
+    finally:
+        bot.chat_state.pop(cid, None)
+
+
 # ─────────────────────────── _save_chat_to_storage/_delete_chat_storage возвращают bool ───────────────────────────
 
 def test_save_chat_to_storage_returns_true_on_success(tmp_path):
@@ -2224,3 +2308,337 @@ def test_or_light_order_no_longer_starts_with_dead_or_worst_offender_models():
     assert "qwen/qwen3-next-80b-a3b-instruct:free" not in bot._OR_LIGHT_ORDER
     assert bot._OR_LIGHT_ORDER[0] not in {"openai/gpt-oss-20b:free", "nvidia/nemotron-3-nano-30b-a3b:free"}
 
+
+# ─────────────────── единый реестр "нездоровых" моделей OpenRouter (аудит техдолга) ───────────────────
+# Раньше "эта модель сейчас плохая" отслеживалось тремя независимыми механизмами
+# (_TEMPORARY_FREE_MODELS/_ROUTER_EXCLUDED_OR_MODELS/точечные вычёркивания из
+# order-списков) — тесты ниже закрепляют, что теперь единственный источник
+# правды — _OR_MODEL_HEALTH, а всё остальное вычисляется из него.
+
+def test_router_excluded_or_models_is_derived_from_health_registry():
+    assert bot._ROUTER_EXCLUDED_OR_MODELS == frozenset(bot._OR_MODEL_HEALTH.keys())
+
+
+def test_model_health_registry_contains_all_three_known_incidents():
+    for model_id in (
+        "cognitivecomputations/dolphin-mistral-24b-venice-edition:free",
+        "qwen/qwen3-coder:free",
+        "tencent/hy3:free",
+        "qwen/qwen3-next-80b-a3b-instruct:free",
+    ):
+        assert model_id in bot._OR_MODEL_HEALTH
+        assert bot._OR_MODEL_HEALTH[model_id].reason
+
+
+def test_check_temporary_free_models_expiry_warns_using_registry_reason(caplog):
+    import logging
+    with caplog.at_level(logging.WARNING, logger="bot"):
+        bot._check_temporary_free_models_expiry()
+    messages = "\n".join(r.getMessage() for r in caplog.records)
+    # qwen3-coder/hy3 промо давно истекло (даты в прошлом) — предупреждение должно
+    # включать причину прямо из реестра, а не отдельный захардкоженный текст.
+    assert "qwen/qwen3-coder:free" in messages
+    assert "tencent/hy3:free" in messages
+
+
+def test_model_health_note_without_promo_expiry_is_permanent_exclusion():
+    # qwen3-next и dolphin-mistral сняты НЕ по истечении промо-акции (нет даты) —
+    # они не должны попадать в предупреждение об истёкшем промо вообще.
+    for model_id in (
+        "qwen/qwen3-next-80b-a3b-instruct:free",
+        "cognitivecomputations/dolphin-mistral-24b-venice-edition:free",
+    ):
+        assert bot._OR_MODEL_HEALTH[model_id].promo_expiry is None
+
+
+# ──────────���──────── каталог моделей генерации изображений (аудит техдолга) ───────────────────
+# Раньше был отдельный HF_IMAGE_MODEL_CACHE + async _hf_fetch_model_catalog(),
+# оба вестигиальные (динамический фетч из HF API убран, каталог всегда 1:1 из
+# HF_IMAGE_MODELS) — заменены на синхронный _hf_model_catalog(). Тестов на этот
+# слой раньше не было вообще; добавлены вместе с упрощением, чтобы не убрать
+# индирекцию "молча".
+
+def test_hf_model_catalog_matches_hf_image_models_exactly():
+    catalog = bot._hf_model_catalog()
+    assert [m["id"] for m in catalog] == list(bot.HF_IMAGE_MODELS.keys())
+    for m in catalog:
+        assert m["name"] == bot.HF_IMAGE_MODELS[m["id"]]["name"]
+
+
+def test_imgmodel_keyboard_marks_current_model_and_paginates():
+    kb = bot._imgmodel_keyboard(bot.DEFAULT_HF_IMAGE_MODEL)
+    all_buttons = [btn for row in kb.inline_keyboard for btn in row]
+    current_buttons = [b for b in all_buttons if b.text.startswith("• ")]
+    assert len(current_buttons) == 1
+    assert bot.HF_IMAGE_MODELS[bot.DEFAULT_HF_IMAGE_MODEL]["name"] in current_buttons[0].text
+
+
+def test_imgmodel_keyboard_clamps_out_of_range_page():
+    # 5 моделей, HF_IMAGE_MODEL_PAGE_SIZE=8 -> всегда ровно одна страница.
+    kb = bot._imgmodel_keyboard(bot.DEFAULT_HF_IMAGE_MODEL, page=99)
+    # Не должно быть кнопки "Дальше >" — 1 страница и так показывает всё.
+    nav_texts = [b.text for row in kb.inline_keyboard for b in row if "Назад" in b.text or "Дальше" in b.text]
+    assert nav_texts == []
+
+# ─────────────────── schema_version персистентного снимка чата (аудит техдолга) ───────────────────
+
+def test_serialize_chat_state_stamps_current_schema_version():
+    state = {"image_model": bot.DEFAULT_HF_IMAGE_MODEL, "history": [], "quota": {}, "recent_media_ids": {}}
+    snapshot = bot._serialize_chat_state(state)
+    assert snapshot["schema_version"] == bot.CHAT_STATE_SCHEMA_VERSION
+
+
+def test_restore_single_chat_accepts_legacy_record_without_schema_version():
+    # Записи, сохранённые до введения schema_version, не имеют этого поля вообще —
+    # восстановление не должно падать и должно вести себя так же, как раньше.
+    cid = 999905
+    try:
+        bot._restore_single_chat(cid, {"image_model": bot.DEFAULT_HF_IMAGE_MODEL, "history": [{"role": "user", "content": "hi"}]})
+        assert bot.chat_state[cid]["history"] == [{"role": "user", "content": "hi"}]
+    finally:
+        bot.chat_state.pop(cid, None)
+
+
+def test_restore_single_chat_accepts_current_schema_version_record():
+    cid = 999906
+    try:
+        snapshot = bot._serialize_chat_state({
+            "image_model": bot.DEFAULT_HF_IMAGE_MODEL, "history": [{"role": "user", "content": "hi"}],
+            "quota": {}, "recent_media_ids": {},
+        })
+        bot._restore_single_chat(cid, snapshot)
+        assert bot.chat_state[cid]["history"] == [{"role": "user", "content": "hi"}]
+    finally:
+        bot.chat_state.pop(cid, None)
+
+# ─────────────────── _TelegramProxyCircuitBreaker (аудит техдолга) ───────────────────
+# Раньше состояние выключателя жило как четыре независимых module-level globals,
+# мутируемых через `global` из двух разных функций — само поведение (порог
+# срабатывания, cooldown, сброс счётчика на успех) нигде не тестировалось
+# напрямую, только опосредованно через _tg_call/telegram_api_call. Инкапсуляция
+# в класс делает это поведение тестируемым в изоляции.
+
+def test_circuit_breaker_starts_closed():
+    breaker = bot._TelegramProxyCircuitBreaker(cooldown_sec=20.0, trip_threshold=3)
+    assert breaker.is_down(time.monotonic()) is False
+
+
+def test_circuit_breaker_does_not_trip_before_threshold():
+    breaker = bot._TelegramProxyCircuitBreaker(cooldown_sec=20.0, trip_threshold=3)
+    assert breaker.note_failure() is False
+    assert breaker.note_failure() is False
+    assert breaker.is_down(time.monotonic()) is False
+
+
+def test_circuit_breaker_trips_at_threshold():
+    breaker = bot._TelegramProxyCircuitBreaker(cooldown_sec=20.0, trip_threshold=3)
+    breaker.note_failure()
+    breaker.note_failure()
+    tripped = breaker.note_failure()
+    assert tripped is True
+    breaker.trip()
+    assert breaker.is_down(time.monotonic()) is True
+
+
+def test_circuit_breaker_success_resets_consecutive_failures():
+    breaker = bot._TelegramProxyCircuitBreaker(cooldown_sec=20.0, trip_threshold=3)
+    breaker.note_failure()
+    breaker.note_failure()
+    breaker.note_success()
+    assert breaker.consecutive_failures == 0
+    # Единичные последующие сбои не должны сразу срабатывать — счётчик правда сброшен.
+    assert breaker.note_failure() is False
+
+
+def test_circuit_breaker_garbage_event_count_never_resets():
+    # В отличие от consecutive_failures, совокупный счётчик для /stats копится
+    # за всё время жизни процесса и не должен сбрасываться на success.
+    breaker = bot._TelegramProxyCircuitBreaker(cooldown_sec=20.0, trip_threshold=3)
+    breaker.note_failure()
+    breaker.note_success()
+    breaker.note_failure()
+    assert breaker.garbage_event_count == 2
+
+
+def test_circuit_breaker_status_text_reflects_state():
+    breaker = bot._TelegramProxyCircuitBreaker(cooldown_sec=20.0, trip_threshold=3)
+    assert "в норме" in breaker.status_text()
+    breaker.note_failure()
+    breaker.note_failure()
+    breaker.note_failure()
+    breaker.trip()
+    assert "ВЫКЛЮЧЕН" in breaker.status_text()
+
+# ─────────────────── ask_gemini: fallback-цикл по цепочке моделей (аудит техдолга) ───────────────────
+# НАЙДЕНО ПРИ АУДИТЕ: внутренняя логика переключения между моделями в ask_gemini
+# (429 -> следующая модель / таймаут -> следующая / прочая ошибка -> следующая /
+# бюджет времени исчерпан -> RouteBudgetExceededError) раньше не была покрыта
+# напрямую НИ ОДНИМ тестом — только опосредованно через _run_route (который
+# мокает саму ask_gemini целиком, не проверяя её внутренний цикл). Тесты ниже
+# фиксируют текущее поведение ДО рефакторинга (объединение классификации ошибок
+# с _or_chat_completion_with_fallback через общие _error_status/_classify_model_error).
+
+def test_ask_gemini_falls_back_to_next_model_on_quota_exhausted():
+    chat_id = 999010
+    calls = []
+
+    class _QuotaExc(Exception):
+        status_code = 429
+
+    def fake_generate_content(*, model, contents, config=None):
+        calls.append(model)
+        if model == "gemini-3.6-flash":
+            raise _QuotaExc("resource_exhausted")
+        return _FakeGeminiResponse(text="Ответ от второй модели")
+
+    fake_client = MagicMock()
+    fake_client.models.generate_content.side_effect = fake_generate_content
+    original_client = bot.client
+    bot.client = fake_client
+    bot.GLOBAL_QUOTA["gemini"].pop("gemini-3.6-flash", None)
+    try:
+        answer = asyncio.run(bot.ask_gemini(chat_id, "Привет", model_chain=["gemini-3.6-flash", "gemini-2.5-flash"]))
+        assert answer == "Ответ от второй модели"
+        assert calls == ["gemini-3.6-flash", "gemini-2.5-flash"]
+        # Модель, отдавшая 429, должна быть помечена исчерпанной (влияет на будущий роутинг).
+        assert bot.GLOBAL_QUOTA["gemini"]["gemini-3.6-flash"]["exhausted_at"] is not None
+    finally:
+        bot.client = original_client
+        bot.chat_state.pop(chat_id, None)
+        bot.GLOBAL_QUOTA["gemini"].pop("gemini-3.6-flash", None)
+
+
+def test_ask_gemini_raises_all_models_exhausted_when_entire_chain_429s():
+    chat_id = 999011
+
+    class _QuotaExc(Exception):
+        status_code = 429
+
+    def fake_generate_content(*, model, contents, config=None):
+        raise _QuotaExc("resource_exhausted")
+
+    fake_client = MagicMock()
+    fake_client.models.generate_content.side_effect = fake_generate_content
+    original_client = bot.client
+    bot.client = fake_client
+    try:
+        with pytest.raises(bot.GeminiAllModelsExhaustedError) as exc_info:
+            asyncio.run(bot.ask_gemini(chat_id, "Привет", model_chain=["gemini-3.6-flash", "gemini-2.5-flash"]))
+        assert set(exc_info.value.exhausted_models) == {"gemini-3.6-flash", "gemini-2.5-flash"}
+    finally:
+        bot.client = original_client
+        bot.chat_state.pop(chat_id, None)
+        bot.GLOBAL_QUOTA["gemini"].pop("gemini-3.6-flash", None)
+        bot.GLOBAL_QUOTA["gemini"].pop("gemini-2.5-flash", None)
+
+
+def test_ask_gemini_falls_back_to_next_model_on_timeout():
+    chat_id = 999012
+    calls = []
+    original_timeout = bot.ROUTE_MODEL_TIMEOUT_SEC
+
+    def fake_generate_content(*, model, contents, config=None):
+        calls.append(model)
+        if model == "gemini-3.6-flash":
+            time.sleep(0.2)  # дольше урезанного ROUTE_MODEL_TIMEOUT_SEC ниже
+        return _FakeGeminiResponse(text="Ответ от второй модели")
+
+    fake_client = MagicMock()
+    fake_client.models.generate_content.side_effect = fake_generate_content
+    original_client = bot.client
+    bot.client = fake_client
+    bot.ROUTE_MODEL_TIMEOUT_SEC = 0.05
+    try:
+        answer = asyncio.run(bot.ask_gemini(chat_id, "Привет", model_chain=["gemini-3.6-flash", "gemini-2.5-flash"]))
+        assert answer == "Ответ от второй модели"
+        assert calls[0] == "gemini-3.6-flash"
+    finally:
+        bot.client = original_client
+        bot.ROUTE_MODEL_TIMEOUT_SEC = original_timeout
+        bot.chat_state.pop(chat_id, None)
+
+
+def test_ask_gemini_falls_back_to_next_model_on_generic_error():
+    chat_id = 999013
+    calls = []
+
+    def fake_generate_content(*, model, contents, config=None):
+        calls.append(model)
+        if model == "gemini-3.6-flash":
+            raise RuntimeError("internal error 500")
+        return _FakeGeminiResponse(text="Ответ от второй модели")
+
+    fake_client = MagicMock()
+    fake_client.models.generate_content.side_effect = fake_generate_content
+    original_client = bot.client
+    bot.client = fake_client
+    try:
+        answer = asyncio.run(bot.ask_gemini(chat_id, "Привет", model_chain=["gemini-3.6-flash", "gemini-2.5-flash"]))
+        assert answer == "Ответ от второй модели"
+        assert calls == ["gemini-3.6-flash", "gemini-2.5-flash"]
+    finally:
+        bot.client = original_client
+        bot.chat_state.pop(chat_id, None)
+
+
+def test_ask_gemini_raises_when_route_budget_exceeded():
+    chat_id = 999014
+
+    def fake_generate_content(*, model, contents, config=None):
+        raise RuntimeError("internal error 500")
+
+    fake_client = MagicMock()
+    fake_client.models.generate_content.side_effect = fake_generate_content
+    original_client = bot.client
+    bot.client = fake_client
+    try:
+        past_deadline = time.monotonic() - 1.0
+        with pytest.raises(bot.RouteBudgetExceededError):
+            asyncio.run(bot.ask_gemini(chat_id, "Привет", model_chain=["gemini-3.6-flash", "gemini-2.5-flash"], deadline=past_deadline))
+    finally:
+        bot.client = original_client
+        bot.chat_state.pop(chat_id, None)
+
+# ─────────────────── _or_chat_completion_with_fallback: единая классификация ошибок ───────────────────
+# Закрепляет, что после унификации с _classify_model_error (см. аудит техдолга)
+# каскад к следующей модели по-прежнему работает одинаково для любого класса
+# ошибки — временной (429/5xx) и внешне "постоянной" (403) — т.к. attempts_per_model
+# всегда 1 в реальном использовании (см. комментарий в самой функции).
+
+def test_or_chat_completion_with_fallback_switches_model_on_rate_limit():
+    async def fake_or_request(path, method="GET", *, json_body=None):
+        model = json_body["model"]
+        if model == "model-a":
+            raise bot.OpenRouterAPIError("rate limit exceeded", status_code=429)
+        return {"choices": [{"message": {"content": "ответ от model-b"}}]}
+
+    original = bot._or_request
+    bot._or_request = fake_or_request
+    try:
+        messages = [{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}]
+        answer, used = asyncio.run(bot._or_chat_completion_with_fallback(messages, ["model-a", "model-b"], "model-a"))
+        assert answer == "ответ от model-b"
+        assert used == "model-b"
+    finally:
+        bot._or_request = original
+
+
+def test_or_chat_completion_with_fallback_switches_model_on_permanent_looking_error():
+    # Даже "постоянная" на вид ошибка (403 forbidden) не должна обрывать переход
+    # к следующей модели — при attempts_per_model=1 переход к следующей модели
+    # происходит независимо от классификации (см. комментарий в самой функции).
+    async def fake_or_request(path, method="GET", *, json_body=None):
+        model = json_body["model"]
+        if model == "model-a":
+            raise bot.OpenRouterAPIError("forbidden", status_code=403)
+        return {"choices": [{"message": {"content": "ответ от model-b"}}]}
+
+    original = bot._or_request
+    bot._or_request = fake_or_request
+    try:
+        messages = [{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}]
+        answer, used = asyncio.run(bot._or_chat_completion_with_fallback(messages, ["model-a", "model-b"], "model-a"))
+        assert answer == "ответ от model-b"
+        assert used == "model-b"
+    finally:
+        bot._or_request = original