Groq provider: qwen head + gpt-oss reserve on light routes (calibrated 21.09.2026), streaming, quota/stats/diag, 8 tests

README.md

@@ -39,7 +39,7 @@ A Telegram bot styled after Claude's tone and personality (direct, warm, light o
 
 ## Features
 
-- **Automatic model routing.** Every message goes to whichever provider actually has what it needs: web search and link reading go to Gemini, everything else defaults to free OpenRouter models, protecting Gemini's tight daily quota.
+- **Automatic model routing.** Every message goes to whichever provider actually has what it needs: plain text starts at Groq (1000 free requests/day), web search and link reading go to Gemini, OpenRouter covers the rest — protecting Gemini's tight daily quota.
 - **Streaming replies** with a self-calibrating typing-speed pacer, so answers type themselves in instead of landing in a few large chunks.
 - **Defenses against prompt injection and identity leaks.** A deterministic input filter plus output scrubbers keep the bot from revealing which model or provider actually answered.
 - **TikTok downloads** without watermarks: video, slideshows (including "live" photo slides), and original sound.

bot.py

@@ -68,7 +68,7 @@ _LOG_LISTENER: logging.handlers.QueueListener | None = None
 
 _SECRET_NAMES = (
     "BOT_TOKEN", "TELEGRAM_TOKEN", "TELEGRAM_BOT_TOKEN", "GEMINI_API_KEY",
-    "OPENROUTER_API_KEY", "OPENROUTER_KEY", "ADMIN_SECRET_SEED",
+    "OPENROUTER_API_KEY", "OPENROUTER_KEY", "GROQ_API_KEY", "ADMIN_SECRET_SEED",
     "_ADMIN_SECRET_SEED", "WEBHOOK_SECRET", "ADMIN_PANEL_KEY",
     "UPSTASH_REDIS_REST_TOKEN", "LUMEN_PROXY_SECRET",
 )
@@ -242,6 +242,9 @@ _OPENROUTER_HTTP_REFERER_ENV_SET = bool(os.getenv("OPENROUTER_HTTP_REFERER", "")
 OPENROUTER_HTTP_REFERER = os.getenv("OPENROUTER_HTTP_REFERER", f"https://t.me/{BOT_USERNAME}").strip()
 OPENROUTER_TITLE = os.getenv("OPENROUTER_TITLE", BOT_USERNAME).strip()
 OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+# Groq — прямой провайдер лёгкого текста (калибровка 21.09.2026): 1000 запросов/день против 50 у OpenRouter.
+GROQ_API_KEY = os.getenv("GROQ_API_KEY", "").strip()
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
 # Раньше у OpenRouter был свой отдельный лимит истории (30), меньший, чем у Gemini
 # (100) — при переключении провайдера (/provider или /model) ощущалось резкое
 # "обнуление" контекста разговора. Теперь история ОБЩАЯ (см. state["history"] в
@@ -526,6 +529,7 @@ from lumen_router_config import (
     _OR_LIGHT_ORDER,
     _OR_HEAVY_ORDER,
     _OR_VISION_ORDER,
+    _GROQ_LIGHT_ORDER,
     GEMINI_TTS_MODELS,
     FISH_AUDIO_TTS_MODEL,
     FISH_AUDIO_ENABLED,
@@ -657,9 +661,11 @@ __all__ = [
     "_pieces_with_waiting_feedback",
     "_gemini_stream_pieces",
     "_openrouter_stream_pieces",
+    "_groq_stream_pieces",
     "_run_streaming_reply",
     "_try_gemini_streaming",
     "_try_openrouter_streaming",
+    "_try_groq_streaming",
     # Точка подмены тестов (см. monkeypatch в tests/) — сам код bot.py её
     # больше не читает напрямую после выноса стриминга.
     "_model_first_chunk_limit",
@@ -693,13 +699,16 @@ __all__ = [
     # Имена из lumen_routes.py код bot.py сам не читает — они нужны как `bot.X`
     # существующим тестам и `_handle_message_core` ниже.
     "OpenRouterAPIError",
+    "GroqAPIError",
     "_or_request",
+    "_groq_request",
     "_or_extract_text",
     "_is_account_wide_or_rate_limit",
     "_probe_or_model_liveness",
     "_or_chat_completion_with_fallback",
     "ask_openrouter_text",
     "ask_openrouter_multimodal",
+    "ask_groq_text",
     "_gemini_history_contents",
     "_build_gemma_identity_contents",
     "_build_gemini_call_config",
@@ -714,6 +723,7 @@ __all__ = [
     "_OR_LIGHT_ORDER",
     "_OR_HEAVY_ORDER",
     "_OR_VISION_ORDER",
+    "_GROQ_LIGHT_ORDER",
     "_history_user_text",
     # Пространство имён genai-типов для тестов (bot.types.Content/...).
     "types",
@@ -917,13 +927,16 @@ from lumen_security import (
 # имён, чтобы `bot.X` в тестах и `_handle_message_core` не менялись.
 from lumen_routes import (
     OpenRouterAPIError,
+    GroqAPIError,
     _or_request,
+    _groq_request,
     _or_extract_text,
     _is_account_wide_or_rate_limit,
     _probe_or_model_liveness,
     _or_chat_completion_with_fallback,
     ask_openrouter_text,
     ask_openrouter_multimodal,
+    ask_groq_text,
     _gemini_history_contents,
     _build_gemma_identity_contents,
     _build_gemini_call_config,
@@ -1011,9 +1024,11 @@ from lumen_streaming import (
     _pieces_with_waiting_feedback,
     _gemini_stream_pieces,
     _openrouter_stream_pieces,
+    _groq_stream_pieces,
     _run_streaming_reply,
     _try_gemini_streaming,
     _try_openrouter_streaming,
+    _try_groq_streaming,
 )
 
 # определение ссылок и упоминаний, триггеры draw/tts, категории медиа —

docs/ARCHITECTURE.md

@@ -7,7 +7,7 @@ This document goes one level deeper than the main [README](../README.md) into ho
 1. Telegram POSTs an update to `/webhook`, authenticated by a secret header (`X-Telegram-Bot-Api-Secret-Token`).
 2. `_handle_message_core` in `bot.py` classifies the message: is it a TikTok link, a `/draw` or `/tts` trigger phrase, a reply to earlier media, plain text, or an attachment?
 3. `_build_route` (`lumen_router_config.py`) turns that classification into an ordered list of `(provider, model_id)` candidates.
-4. `_run_route` tries the first candidate. If a whole provider's chain fails, it falls back to the other provider, except where that's physically impossible (only Gemini can read links or analyze video/audio).
+4. `_run_route` tries the first candidate. If a whole provider's chain fails, it falls back to the next provider in the route, except where that's physically impossible (only Gemini can read links or analyze video/audio).
 5. The reply streams into the chat if the request qualifies (see [Streaming](#streaming--typing-pace) below), or is sent as a single message otherwise.
 
 ## Automatic model routing
@@ -17,10 +17,10 @@ Routing is fully automatic: the router builds a fresh candidate list for every m
 - **A YouTube or website link** → Gemini only. It's the only provider that can read page content (`url_context`) or analyze a video by URL.
 - **A video or audio attachment** → Gemini only. OpenRouter's multimodal models only accept images as base64.
 - **An image attachment, no live-info need** → free OpenRouter vision models first, Gemini as a reserve.
-- **Needs current information** (a lightweight keyword heuristic: "now," "today," "price," "who is currently...") → Gemini, prioritizing the models with a real search-grounding quota, then OpenRouter as a reserve.
-- **Plain text, no attachments, no freshness need** (the most common case) → straight to OpenRouter. Heavier requests (code, multi-step reasoning, caught by another lightweight heuristic) get routed to the stronger free OpenRouter models first.
+- **Needs current information** (a lightweight keyword heuristic: "now," "today," "price," "who is currently...") → Gemini, prioritizing the models with a real search-grounding quota, then OpenRouter as a reserve, Groq last (knowledge-only answer if both are down).
+- **Plain text, no attachments, no freshness need** (the most common case) → Groq first (1000 free requests/day: Qwen, then gpt-oss), then OpenRouter. Heavier requests (code, multi-step reasoning, caught by another lightweight heuristic) get routed to the stronger free OpenRouter models first.
 
-The reasoning: Gemini's free quota (roughly 20 requests per day for the flagship model) is the scarcest resource in the system, so it's only spent where a capability unique to Gemini is actually needed. Everything else, the bulk of ordinary messages, runs on OpenRouter's much more generous free tier.
+The reasoning: Gemini's free quota (roughly 20 requests per day for the flagship model) is the scarcest resource in the system, so it's only spent where a capability unique to Gemini is actually needed. Everything else, the bulk of ordinary messages, runs on Groq (1000/day) and OpenRouter's free tiers.
 
 Models that the router should never pick are tracked in a single registry, `_OR_MODEL_HEALTH` (`lumen_router_config.py`), each with a dated reason: the provider dropped the free tier, or the model turned out to be uncensored and a poor fit for Lumen's persona. Nothing is removed on speculation, only on confirmed evidence from production logs (`HTTP 404`, `"no endpoints,"` etc.).
 
@@ -32,7 +32,7 @@ Each model is tried exactly once per route, with no retries: a single failure (t
 
 ## Streaming & typing pace
 
-For the first candidate in a route (plain text, no attachments, no links), Lumen streams the reply by repeatedly editing one message, the same mechanism for both Gemini (`generate_content_stream`) and OpenRouter (SSE over `chat/completions`).
+For the first candidate in a route (plain text, no attachments, no links), Lumen streams the reply by repeatedly editing one message, the same mechanism for Gemini (`generate_content_stream`), OpenRouter and Groq (SSE over `chat/completions`).
 
 Telegram won't let a bot edit one message more than about once a second, so true token-by-token output isn't possible regardless of how fast the model generates text. Instead, `lumen_typing_pace.py` tracks each `provider:model` pair's real observed characters-per-second and reveals a growing slice of the buffered text at that pace, capped by whatever has actually arrived. If a backend returns the whole answer in one large chunk (common for free OpenRouter models, since the same `:free` slug can be served by different backends depending on load), a short "catch-up" phase finishes revealing it smoothly instead of dumping it all at once, capped at `STREAM_TYPING_MAX_CATCHUP_TICKS × STREAM_TYPING_TICK_SEC` seconds.
 
@@ -42,7 +42,7 @@ If the streaming attempt for the head-of-route model fails before showing any te
 
 ### Manual smoke test before touching streaming code
 
-Streaming is covered only by mocked clients; no test exercises a real Gemini or OpenRouter SSE stream. Before merging changes to `_run_streaming_reply`, `_gemini_stream_pieces`, `_openrouter_stream_pieces`, or `lumen_typing_pace.py`, check by hand in a real chat:
+Streaming is covered only by mocked clients; no test exercises a real Gemini or OpenRouter SSE stream. Before merging changes to `_run_streaming_reply`, `_gemini_stream_pieces`, `_openrouter_stream_pieces`, `_groq_stream_pieces`, or `lumen_typing_pace.py`, check by hand in a real chat:
 
 1. A short message (fits in one edit): once via Gemini, once via OpenRouter.
 2. A long message (past `TG_MAX_LEN`): confirm it splits into multiple messages and continues correctly.

docs/ENVIRONMENT.md

@@ -48,6 +48,7 @@ Before publishing, configure the same `LUMEN_PROXY_SECRET` on HF and every Deno
 | Variable | Default | Purpose |
 |---|---|---|
 | `OPENROUTER_API_KEY` / `OPENROUTER_KEY` | — | OpenRouter API key. Without it, the router sends everything to Gemini, which burns through its much smaller quota fast. |
+| `GROQ_API_KEY` | — | Groq API key (free plan, no card: 1000 req/day). Heads plain-text routes; without it OpenRouter heads them as before. |
 | `OPENROUTER_HTTP_REFERER` | `https://t.me/{BOT_USERNAME}` | `HTTP-Referer` header sent with OpenRouter requests. |
 | `OPENROUTER_TITLE` | `BOT_USERNAME` | App title header sent with OpenRouter requests. |
 | `POLLINATIONS_IMAGE_MODEL` | `flux` | Default image-generation model (used only if the prompt doesn't match a more specific style). Renamed from `HF_IMAGE_MODEL` (Sept 2026) — the backend is Pollinations.ai, not Hugging Face; the old name is no longer read. |

lumen_admin.py

@@ -129,6 +129,7 @@ async def network_diagnostics(request: Request) -> dict[str, Any]:
         "gemini_api": "https://generativelanguage.googleapis.com",
         "huggingface": "https://huggingface.co",
         "openrouter": "https://openrouter.ai",
+        "groq_api": "https://api.groq.com",
         "tikwm": "https://www.tikwm.com",
         "pollinations": "https://image.pollinations.ai",
         "upstash": bot.UPSTASH_REDIS_REST_URL if bot.USE_UPSTASH else "https://upstash.com",

lumen_commands.py

@@ -440,6 +440,14 @@ async def cmd_stats(message: Message) -> None:
     ]
     or_text = "\n".join(or_lines) or _noData
 
+    # Groq — та же разбивка по моделям (прямой провайдер с собственным дневным лимитом).
+    groq_quota = bot.GLOBAL_QUOTA.get("groq", {})
+    groq_lines = [
+        f"  • {mid}: {e.get('used', 0)}{_limitTag if e.get('exhausted_at') else ''}"
+        for mid, e in sorted(groq_quota.items(), key=lambda kv: -(kv[1].get("used") or 0))
+    ]
+    groq_text = "\n".join(groq_lines) or _noData
+
     # Состояние прокси — из самого breaker'а (раньше команда лезла в четыре глобала напрямую).
     proxy_line = bot._tg_proxy_breaker.status_text()
 
@@ -451,7 +459,8 @@ async def cmd_stats(message: Message) -> None:
         f"Аптайм процесса: {uptime_str}\n"
         f"Счётчики квоты за сутки: {quota_day} (America/Los_Angeles, сбрасываются автоматически)\n\n"
         f"<b>Gemini — запросов по моделям:</b>\n{gemini_text}\n\n"
-        f"<b>OpenRouter — запросов по моделям:</b>\n{or_text}"
+        f"<b>OpenRouter — запросов по моделям:</b>\n{or_text}\n\n"
+        f"<b>Groq — запросов по моделям:</b>\n{groq_text}"
         f"{proxy_line}"
     )
     await bot._tg_call(message.reply, text, parse_mode=ParseMode.HTML)

lumen_router_config.py

@@ -197,6 +197,10 @@ _KNOWN_MODEL_IDS_FOR_LEAK_DETECTION: list[str] = [
     "inclusionai/ling-3.0-flash-vl:free",
     "liquid/lfm-2.5-2.6b:free",
     "gemini-3.8-flash",
+    "openrouter/free",
+    # Groq-ID без :free-суффикса — те же семейства, что выше через OpenRouter; дословно в ответе им тоже не место.
+    "qwen/qwen3.8-27b",
+    "openai/gpt-oss-120b",
 ]
 TEXT_MODEL_ORDER = _KNOWN_MODEL_IDS_FOR_LEAK_DETECTION  # алиас для обратной совместимости
 # Аудит 02.08.2026 (логи + каталог): laguna-s-2.1 и ling-3.0-flash, калибровку не проходили (только факт free-квоты).
@@ -310,6 +314,17 @@ def _or_route(models: list[str]) -> list[tuple[str, str]]:
 def _gemini_route(models: list[str]) -> list[tuple[str, str]]:
     return [("gemini", m) for m in models]
 
+# ── Groq (прямой провайдер, не через OpenRouter) ──
+# Калибровка русского живьём 21.09.2026 (4 пробы на модель через API с VPN): Qwen отвечает чисто и по делу, gpt-oss-120b тоже верен, но представляется ChatGPT от OpenAI (ловит фильтр утечек) и тратит 30-70 reasoning-токенов на ответ — они едят минутный бюджет. Поэтому Qwen голова, gpt-oss второй. Лимиты free-плана по офиц. доке: 30 RPM / 1000 RPD / 8K TPM / 200K TPD на модель.
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+_GROQ_LIGHT_ORDER: list[str] = [
+    "qwen/qwen3.8-27b",
+    "openai/gpt-oss-120b",
+]
+
+def _groq_route(models: list[str]) -> list[tuple[str, str]]:
+    return [("groq", m) for m in models]
+
 
 # ── "Лёгкие" запросы — САМЫЙ ЧАСТЫЙ маршрут, целиком OpenRouter (квоту Gemini не трогаем).
 #
@@ -468,12 +483,13 @@ def _build_route(
     if needs_freshness:
         # Текст без вложений, но нужна свежая информация — только у Gemini
         # реально есть поиск; OpenRouter в конце как резерв на случай, если
-        # Gemini исчерпан целиком (без поиска, но хоть какой-то ответ).
-        return _gemini_route(GEMINI_SEARCH_CHAIN) + _or_route(_OR_HEAVY_ORDER if is_heavy else _OR_LIGHT_ORDER)
+        # Gemini исчерпан целиком (без поиска, но хоть какой-то ответ), Groq —
+        # последним (ответ по знаниям, если легли оба).
+        return _gemini_route(GEMINI_SEARCH_CHAIN) + _or_route(_OR_HEAVY_ORDER if is_heavy else _OR_LIGHT_ORDER) + _groq_route(_GROQ_LIGHT_ORDER)
 
     # Основной случай: обычный текст без вложений/ссылок/признаков нужды в
-    # интернете — целиком к OpenRouter, Gemini — резерв на случай отказа всей
-    # цепочки OpenRouter разом.
+    # интернете — сначала Groq (1000/день против 50 у OpenRouter — главный объём),
+    # дальше OpenRouter, Gemini — резерв на случай отказа обоих разом.
     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)
+    return _groq_route(_GROQ_LIGHT_ORDER) + _or_route(_OR_LIGHT_ORDER) + _gemini_route(GEMINI_SEARCH_CHAIN)

lumen_routes.py

@@ -50,6 +50,41 @@ class OpenRouterAPIError(RuntimeError):
         self.status_code = status_code
         self.payload = payload
 
+class GroqAPIError(RuntimeError):
+    """То же, что OpenRouterAPIError, для прямого Groq-эндпоинта (статус кладём рядом — его читает _error_status/_classify_model_error)."""
+    def __init__(self, message: str, status_code: int | None = None, payload: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+async def _groq_request(path: str, method: str = "GET", *, json_body: dict | None = None) -> Any:
+    """Прямой запрос к Groq (OpenAI-совместимый API) — по образцу _or_request: тот же бюджет попытки, та же вычистка ключа из ошибок."""
+    import bot
+    if not bot.GROQ_API_KEY:
+        raise bot.GroqAPIError("GROQ_API_KEY is not set")
+    headers = {"Authorization": f"Bearer {bot.GROQ_API_KEY}"}
+    if json_body is not None:
+        headers["Content-Type"] = "application/json"
+    session = await bot._get_http_session()
+    url = f"{bot.GROQ_BASE_URL}/{path.lstrip('/')}"
+    try:
+        async with session.request(
+            method.upper(), url, headers=headers, json=json_body,
+            timeout=aiohttp.ClientTimeout(total=bot.ROUTE_MODEL_TIMEOUT_SEC, connect=10.0)
+        ) as resp:
+            if resp.status >= 400:
+                payload = await resp.json(content_type=None)
+                msg = payload.get("error", {}).get("message") or f"HTTP {resp.status}"
+                raise bot.GroqAPIError(msg, status_code=resp.status, payload=payload)
+            return await resp.json(content_type=None)
+    except bot.GroqAPIError:
+        raise
+    except Exception as exc:
+        exc_str = str(exc) or repr(exc) or exc.__class__.__name__
+        if bot.GROQ_API_KEY:
+            exc_str = exc_str.replace(bot.GROQ_API_KEY, "<KEY>")
+        raise bot.GroqAPIError(f"Groq network error: {exc_str}") from exc
+
 async def _or_request(path: str, method: str = "GET", *, json_body: dict | None = None) -> Any:
     import bot
     if not bot.OPENROUTER_API_KEY:
@@ -106,15 +141,18 @@ async def _probe_or_model_liveness() -> None:
         return
     day_idx = date.today().timetuple().tm_yday
     lists = {
-        "_OR_LIGHT_ORDER": _OR_LIGHT_ORDER,
-        "_OR_HEAVY_ORDER": _OR_HEAVY_ORDER,
-        "_OR_VISION_ORDER": _OR_VISION_ORDER,
+        "_OR_LIGHT_ORDER": (_OR_LIGHT_ORDER, bot._or_request),
+        "_OR_HEAVY_ORDER": (_OR_HEAVY_ORDER, bot._or_request),
+        "_OR_VISION_ORDER": (_OR_VISION_ORDER, bot._or_request),
     }
-    heads = {name: models[day_idx % len(models)] for name, models in lists.items() if models}
-    for list_name, model_id in heads.items():
+    if bot.GROQ_API_KEY:
+        from lumen_router_config import _GROQ_LIGHT_ORDER
+        lists["_GROQ_LIGHT_ORDER"] = (_GROQ_LIGHT_ORDER, bot._groq_request)
+    heads = {name: (models[day_idx % len(models)], req) for name, (models, req) in lists.items() if models}
+    for list_name, (model_id, req_fn) in heads.items():
         try:
             payload = {"model": model_id, "messages": [{"role": "user", "content": "ping"}], "stream": False}
-            await bot._or_request("chat/completions", "POST", json_body=payload)
+            await req_fn("chat/completions", "POST", json_body=payload)
         except Exception as exc:
             txt = bot._error_text(exc).strip() or exc.__class__.__name__
             kind = bot._classify_model_error(bot._error_status(exc, txt), txt)
@@ -188,10 +226,61 @@ async def ask_openrouter_text(chat_id: int, user_text: str, model_chain: list[st
     history.append({"role": "assistant", "content": answer})
     ctx.clear()
     if len(history) > bot.SHARED_HISTORY_MAX_LEN:
-         del history[:-bot.SHARED_HISTORY_MAX_LEN]
+        del history[:-bot.SHARED_HISTORY_MAX_LEN]
     bot._record_quota_usage("openrouter", model_trial)
     return answer
 
+async def ask_groq_text(chat_id: int, user_text: str, model_chain: list[str], *, deadline: float | None = None) -> str:
+    """Обычный текстовый запрос через прямой Groq — по образцу ask_openrouter_text: одна попытка на модель, скраб утечек, расход в квоту "groq". Сообщения строит общий _build_openrouter_turn_messages (тот же OpenAI-формат)."""
+    import bot
+    from lumen_router_config import _GROQ_LIGHT_ORDER
+    state = bot.get_state(chat_id)
+    history = state.setdefault("history", [])
+    ctx = state.get("ctx", deque())
+    # Дедупликация с сохранением приоритета роутера; запасной — голова актуального _GROQ_LIGHT_ORDER.
+    trial_models = list(dict.fromkeys(model_chain)) or [_GROQ_LIGHT_ORDER[0]]
+    primary_model_id = trial_models[0]
+    messages = bot._build_openrouter_turn_messages(chat_id, user_text, primary_model_id)
+
+    last_exc: Exception | None = None
+    tried: list[str] = []
+    for model_trial in trial_models:
+        if deadline is not None and time.monotonic() > deadline:
+            log.warning('[groq] Route time budget exhausted before model %s. Tried: %s', model_trial, ", ".join(tried) or "none")
+            raise bot.RouteBudgetExceededError(tried)
+        tried.append(model_trial)
+        messages[0]["content"] = bot.get_system_prompt(model_trial)
+        attempt_start = time.monotonic()
+        try:
+            payload = {"model": model_trial, "messages": messages, "stream": False}
+            resp = await bot._groq_request("chat/completions", "POST", json_body=payload)
+            choices = resp.get("choices") or []
+            answer = ""
+            if choices:
+                answer = bot._or_extract_text(choices[0].get("message") or "")
+            answer = answer.strip()
+            if not answer:
+                # Пустой ответ — повод попробовать следующую модель (тот же прод-кейс 17.09.2026, что у OR/Gemini).
+                raise RuntimeError(f"Model {model_trial} returned an empty response")
+            answer = _scrub_identity_leak(answer, source=f"groq_chat_completion:{model_trial}")
+            log.info('[groq] Successful response from model %s (primary=%s, models tried: %d)', model_trial, primary_model_id, len(tried))
+            _record_model_latency(_model_speed_key("groq", model_trial), total_sec=time.monotonic() - attempt_start)
+            break
+        except Exception as exc:
+            last_exc = exc
+            log.warning("[groq] Model %s failed: %s. Switching to next candidate...", model_trial, str(last_exc) or last_exc.__class__.__name__)
+    else:
+        raise last_exc or RuntimeError("No candidate model returned an answer.")
+
+    # В историю — чистый текст пользователя, как у остальных провайдеров.
+    history.append({"role": "user", "content": user_text})
+    history.append({"role": "assistant", "content": answer})
+    ctx.clear()
+    if len(history) > bot.SHARED_HISTORY_MAX_LEN:
+        del history[:-bot.SHARED_HISTORY_MAX_LEN]
+    bot._record_quota_usage("groq", model_trial)
+    return answer
+
 async def ask_openrouter_multimodal(
     chat_id: int, user_text: str, media_tuple: tuple[bytes, str], media_filename: str,
     model_chain: list[str], *, deadline: float | None = None,
@@ -556,6 +645,8 @@ def _route_error_reply_text(exc: Exception, head_model: str, *, youtube_url_to_a
         return bot._lang_t(lang, "err_budget")
     if isinstance(exc, bot.OpenRouterAPIError):
         return bot._or_error_msg(exc, "text", lang)
+    if isinstance(exc, bot.GroqAPIError):
+        return bot._or_error_msg(exc, "groq", lang)
     return bot._gemini_error_msg(exc, head_model, lang)
 
 
@@ -581,11 +672,12 @@ async def _run_route(
     route = _reorder_route_by_speed(route)
     deadline = time.monotonic() + bot.ROUTE_TOTAL_BUDGET_SEC
 
-    groups: dict[str, list[str]] = {"gemini": [], "openrouter": []}
+    groups: dict[str, list[str]] = {"gemini": [], "openrouter": [], "groq": []}
     for provider, model_id in route:
-        groups[provider].append(model_id)
+        groups.setdefault(provider, []).append(model_id)
     first_provider = route[0][0]
-    provider_order = [first_provider, "openrouter" if first_provider == "gemini" else "gemini"]
+    # Порядок провайдеров — по первому появлению в маршруте (для прежних двухпровайдерных маршрутов то же самое: голова + второй).
+    provider_order = list(dict.fromkeys(p for p, _ in route))
 
     # Стримим только голову маршрута; плейсхолдер "…" переиспользуем под финальный текст следующей модели, а не сносим.
     tried_stream_model: str | None = None
@@ -607,6 +699,13 @@ async def _run_route(
                 return streamed, True
             tried_stream_model, tried_stream_provider = head_model, "openrouter"
             reusable_placeholder = placeholder
+        elif first_provider == "groq":
+            streamed, placeholder = await bot._try_groq_streaming(chat_id, ai_prompt, message, head_model)
+            if streamed is not None:
+                log.info('[router] chat=%s response received via streaming (groq:%s)', chat_id, head_model)
+                return streamed, True
+            tried_stream_model, tried_stream_provider = head_model, "groq"
+            reusable_placeholder = placeholder
 
     is_video_or_audio = bool(media) and not media[0][1].startswith("image/")
     last_exc: Exception | None = None
@@ -625,6 +724,8 @@ async def _run_route(
         try:
             if provider == "gemini":
                 ans = await bot.ask_gemini(chat_id, ai_prompt, media=media, youtube_url=youtube_url, model_chain=ids, deadline=deadline)
+            elif provider == "groq":
+                ans = await bot.ask_groq_text(chat_id, ai_prompt, model_chain=ids, deadline=deadline)
             elif media:
                 ans = await bot.ask_openrouter_multimodal(chat_id, ai_prompt, media[0], media_filename, model_chain=ids, deadline=deadline)
             else:

lumen_streaming.py

@@ -145,6 +145,52 @@ async def _openrouter_stream_pieces(model_id: str, messages: list[dict]):
             if piece:
                 yield piece
 
+async def _groq_stream_pieces(model_id: str, messages: list[dict]):
+    """Куски от Groq: тот же OpenAI-SSE, что у OpenRouter (Groq — OpenAI-совместимый API). Таймаут на строку — STREAM_CHUNK_TIMEOUT_SEC."""
+    import bot
+    if not bot.GROQ_API_KEY:
+        raise bot.GroqAPIError("GROQ_API_KEY is not set")
+    headers = {
+        "Authorization": f"Bearer {bot.GROQ_API_KEY}",
+        "Content-Type": "application/json",
+    }
+    session = await bot._get_http_session()
+    url = f"{bot.GROQ_BASE_URL}/chat/completions"
+    payload = {"model": model_id, "messages": messages, "stream": True}
+    async with session.post(url, headers=headers, json=payload, timeout=aiohttp.ClientTimeout(total=None, connect=12.0)) as resp:
+        if resp.status >= 400:
+            body = await resp.read()
+            raise bot.GroqAPIError(f"HTTP {resp.status}: {body[:300]!r}", status_code=resp.status)
+        line_iter = resp.content.__aiter__()
+        while True:
+            try:
+                raw_line = await asyncio.wait_for(line_iter.__anext__(), timeout=bot.STREAM_CHUNK_TIMEOUT_SEC)
+            except StopAsyncIteration:
+                break
+            line = raw_line.decode("utf-8", errors="ignore").strip()
+            if not line or not line.startswith("data:"):
+                continue
+            data_str = line[len("data:"):].strip()
+            if data_str == "[DONE]":
+                break
+            try:
+                obj = json.loads(data_str)
+            except Exception:
+                continue
+            # Ошибка внутри SSE-чанка — как у OpenRouter: поднимаем, дальше штатно (ранний сбой — откат, поздний — пометка).
+            err_obj = obj.get("error")
+            if err_obj:
+                err_msg = err_obj.get("message") if isinstance(err_obj, dict) else str(err_obj)
+                err_code = err_obj.get("code") if isinstance(err_obj, dict) else None
+                raise bot.GroqAPIError(err_msg or "Groq returned an error in the stream body", status_code=err_code)
+            choices = obj.get("choices") or []
+            if not choices:
+                continue
+            delta = choices[0].get("delta") or {}
+            piece = delta.get("content") or ""
+            if piece:
+                yield piece
+
 async def _run_streaming_reply(
     chat_id: int, user_text: str, message: Message, *, provider: str, model_id: str, piece_agen,
 ) -> tuple[str | None, Message | None]:
@@ -334,3 +380,11 @@ async def _try_openrouter_streaming(chat_id: int, user_text: str, message: Messa
     # Генератор — через bot.: тесты подменяют bot._openrouter_stream_pieces фейком.
     piece_agen = bot._openrouter_stream_pieces(model_id, messages)
     return await _run_streaming_reply(chat_id, user_text, message, provider="openrouter", model_id=model_id, piece_agen=piece_agen)
+
+async def _try_groq_streaming(chat_id: int, user_text: str, message: Message, model_id: str) -> tuple[str | None, Message | None]:
+    """Обёртка _run_streaming_reply для Groq (SSE через chat/completions)."""
+    import bot
+    messages = bot._build_openrouter_turn_messages(chat_id, user_text, model_id)
+    # Генератор — через bot.: тесты подменяют bot._groq_stream_pieces фейком.
+    piece_agen = bot._groq_stream_pieces(model_id, messages)
+    return await _run_streaming_reply(chat_id, user_text, message, provider="groq", model_id=model_id, piece_agen=piece_agen)

tests/test_bot_routes.py

@@ -447,6 +447,34 @@ def test_run_route_falls_back_from_failed_openrouter_stream_to_non_streaming():
         bot.ask_openrouter_text = original_or_text
 
 
+def test_run_route_tries_groq_head_with_stream_fallback_to_text():
+    # Groq-подключение 21.09.2026: голова-groq стримится через _try_groq_streaming, при раннем сбое — обычный ask_groq_text без пере-пробы упавшей модели.
+    chat_id = 999703
+
+    async def fake_groq_stream_fail(cid, prompt, message, model_id):
+        return None, None
+
+    calls = []
+
+    async def fake_groq_text(cid, prompt, model_chain, deadline=None):
+        calls.append(model_chain)
+        return "Ответ Groq без стрима"
+
+    original_stream = bot._try_groq_streaming
+    original_groq_text = bot.ask_groq_text
+    bot._try_groq_streaming = fake_groq_stream_fail
+    bot.ask_groq_text = fake_groq_text
+    try:
+        route = [("groq", "qwen/qwen3.8-27b"), ("groq", "openai/gpt-oss-120b")]
+        ans, sent = asyncio.run(bot._run_route(chat_id, "привет", route, message=None, allow_stream=True))
+        assert ans == "Ответ Groq без стрима"
+        assert sent is False
+        assert calls[0] == ["openai/gpt-oss-120b"]
+    finally:
+        bot._try_groq_streaming = original_stream
+        bot.ask_groq_text = original_groq_text
+
+
 def test_run_route_reuses_stream_placeholder_when_fallback_succeeds():
     # Регрессия на реальный найденный при тестировании баг: раньше при неудачном
     # стриме плейсхолдер "…" тут же удалялся, а следующая модель отправляла
@@ -919,3 +947,75 @@ def test_system_prompt_en_keeps_key_guards():
 def test_get_system_prompt_header_english():
     assert "CURRENT TIME INFORMATION" in bot.get_system_prompt()
 
+
+def test_ask_groq_text_success_records_groq_quota(monkeypatch):
+    # Groq-подключение 21.09.2026: успешный ответ пишется в историю и в квоту "groq", как у остальных провайдеров.
+    from collections import deque
+    chat_id = 999701
+    monkeypatch.setattr(bot, "get_state", lambda cid: {"history": [], "ctx": deque()})
+
+    async def fake_groq_request(path, method="GET", *, json_body=None):
+        assert json_body["model"] == "qwen/qwen3.8-27b"
+        return {"choices": [{"message": {"content": "Канберра."}}]}
+
+    monkeypatch.setattr(bot, "_groq_request", fake_groq_request)
+    monkeypatch.setattr(bot, "GROQ_API_KEY", "fake-key")
+    recorded = {}
+    monkeypatch.setattr(bot, "_record_quota_usage", lambda provider, model: recorded.setdefault("v", (provider, model)))
+    answer = asyncio.run(bot.ask_groq_text(chat_id, "Столица Австралии?", model_chain=["qwen/qwen3.8-27b"]))
+    assert answer == "Канберра."
+    assert recorded["v"] == ("groq", "qwen/qwen3.8-27b")
+
+
+def test_ask_groq_text_falls_back_to_next_model(monkeypatch):
+    # Одна попытка на модель: первая падает — идём на вторую, а не ретраим.
+    from collections import deque
+    chat_id = 999702
+    monkeypatch.setattr(bot, "get_state", lambda cid: {"history": [], "ctx": deque()})
+    seen = []
+
+    async def fake_groq_request(path, method="GET", *, json_body=None):
+        seen.append(json_body["model"])
+        if json_body["model"] == "qwen/qwen3.8-27b":
+            raise bot.GroqAPIError("overloaded", status_code=503)
+        return {"choices": [{"message": {"content": "ok"}}]}
+
+    monkeypatch.setattr(bot, "_groq_request", fake_groq_request)
+    monkeypatch.setattr(bot, "GROQ_API_KEY", "fake-key")
+    monkeypatch.setattr(bot, "_record_quota_usage", lambda provider, model: None)
+    answer = asyncio.run(bot.ask_groq_text(chat_id, "привет", model_chain=["qwen/qwen3.8-27b", "openai/gpt-oss-120b"]))
+    assert answer == "ok"
+    assert seen == ["qwen/qwen3.8-27b", "openai/gpt-oss-120b"]
+
+
+def test_groq_request_requires_key(monkeypatch):
+    # Без GROQ_API_KEY — понятная ошибка, а не сетевой вызов в никуда.
+    monkeypatch.setattr(bot, "GROQ_API_KEY", "")
+    with pytest.raises(bot.GroqAPIError):
+        asyncio.run(bot._groq_request("chat/completions", "POST", json_body={"model": "x"}))
+
+
+def test_groq_request_scrubs_api_key_from_network_exception_message(monkeypatch):
+    # Тот же defense-in-depth, что у _or_request: ключ не должен светиться в тексте ошибок.
+    class _FakeSessionRaisingWithKey:
+        def request(self, *args, **kwargs):
+            raise RuntimeError("connection failed, headers: Bearer fake-groq-key-123")
+
+    async def fake_get_http_session():
+        return _FakeSessionRaisingWithKey()
+
+    monkeypatch.setattr(bot, "_get_http_session", fake_get_http_session)
+    monkeypatch.setattr(bot, "GROQ_API_KEY", "fake-groq-key-123")
+    with pytest.raises(bot.GroqAPIError) as exc_info:
+        asyncio.run(bot._groq_request("chat/completions", "POST", json_body={"model": "x"}))
+    assert "fake-groq-key-123" not in str(exc_info.value)
+    assert "<KEY>" in str(exc_info.value)
+
+
+def test_route_error_reply_text_maps_groq_error():
+    # Ошибка Groq — пользовательский текст через общую классификацию, без сырого API.
+    exc = bot.GroqAPIError("Rate limit reached", status_code=429)
+    text = bot._route_error_reply_text(exc, "qwen/qwen3.8-27b", youtube_url_to_analyze=None, lang="en")
+    assert "Rate limit reached" not in text
+    assert text.strip() != ""
+

tests/test_bot_streaming.py

@@ -179,6 +179,36 @@ def test_openrouter_stream_pieces_parses_sse_chunks():
         bot.OPENROUTER_API_KEY = original_key
 
 
+def test_groq_stream_pieces_parses_sse_chunks():
+    # Groq-подключение 21.09.2026: тот же OpenAI-SSE, что у OpenRouter — куски собираются, [DONE] завершает.
+    lines = [
+        'data: {"choices":[{"delta":{"content":"Кан"}}]}\n'.encode("utf-8"),
+        'data: {"choices":[{"delta":{"content":"берра"}}]}\n'.encode("utf-8"),
+        b"data: [DONE]\n",
+    ]
+    fake_resp = _FakeSSEResponse(lines)
+    fake_session = _FakeSessionForSSE(fake_resp)
+
+    async def fake_get_http_session():
+        return fake_session
+
+    original_get_session = bot._get_http_session
+    original_key = bot.GROQ_API_KEY
+    bot._get_http_session = fake_get_http_session
+    bot.GROQ_API_KEY = "fake-key"
+    try:
+        async def collect():
+            pieces = []
+            async for piece in bot._groq_stream_pieces("qwen/qwen3.8-27b", [{"role": "user", "content": "hi"}]):
+                pieces.append(piece)
+            return pieces
+        pieces = asyncio.run(collect())
+        assert pieces == ["Кан", "берра"]
+    finally:
+        bot._get_http_session = original_get_session
+        bot.GROQ_API_KEY = original_key
+
+
 def test_openrouter_stream_pieces_raises_on_http_error_status():
     fake_resp = _FakeSSEResponse([], status=500)
     fake_session = _FakeSessionForSSE(fake_resp)

tests/test_lumen_router_config.py

@@ -114,13 +114,16 @@ def test_build_route_freshness_query_prioritizes_search_capable_gemini_models():
     assert route[0][0] == "gemini"
     # OpenRouter должен присутствовать как резерв на случай полного отказа Gemini.
     assert any(p == "openrouter" for p, _ in route)
+    # Groq — последним резервом (ответ по знаниям, если легли оба).
+    assert route[-1][0] == "groq"
 
 
-def test_build_route_plain_text_prefers_openrouter_to_save_gemini_quota():
-    # Основной сценарий из требования: обычный текст без вложений/ссылок/нужды
-    # в интернете — должен идти в OpenRouter первым делом, а не в Gemini.
+def test_build_route_plain_text_prefers_groq_to_save_quotas():
+    # Обычный текст — сначала Groq (1000/день против 50 у OpenRouter, калибровка 21.09.2026),
+    # дальше OpenRouter, Gemini — резервом.
     route = lumen_router_config._build_route(needs_youtube=False, needs_website=False, media_mime=None, is_heavy=False, needs_freshness=False)
-    assert route[0][0] == "openrouter"
+    assert route[0] == ("groq", "qwen/qwen3.8-27b")
+    assert any(p == "openrouter" for p, _ in route)
     assert any(p == "gemini" for p, _ in route)  # Gemini всё ещё есть как резерв