@danhachuel/pandanews 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 Todas as versões publicadas são registradas aqui antes do publish (regra em AGENTS.md). A etiqueta visual usa PATCH de dois dígitos (ex.: 0.1.00); o registry npm normaliza para a versão canônica (ex.: 0.1.0).
 
+## 0.4.07 (2026-11-08)
+
+- **CORREÇÃO DEFINITIVA da NVIDIA NIM — réplica do Thunderbolt**: `backend/core/llm_router.py` reescrito para falar com provedores OpenAI-compatible por **HTTP direto** (`POST {base_url}/chat/completions`, `Authorization: Bearer`, `Content-Type: application/json`, `Accept: application/json`), a mesma estrutura que funciona no projeto Thunderbolt — `requests` trocado por `httpx`, já dependência do projeto
+- **Causa raiz 1 — dependência fantasma**: o 0.4.05/0.4.06 importava `from openai import APIStatusError, OpenAI`, mas `openai` **não está** em `requirements.txt`. Em instalação nova o backend morria com `ImportError` antes de qualquer chamada — era a exceção quebrando o fluxo antes da troca de provedor. A dependência foi eliminada: nada de SDK extra para instalar
+- **Causa raiz 2 — modelo em fim de vida**: o default `meta/llama-3.3-70b-instruct` chegou ao fim da vida em 2026-08-26 e devolve **HTTP 410 Gone**; `meta/llama-3.1-nemotron-70b-instruct` devolve **HTTP 404 page not found**. O default agora é `mistralai/mistral-large-2-instruct`, verificado no catálogo ao vivo (`GET https://integrate.api.nvidia.com/v1/models`)
+- **Endpoint à prova de 404**: a Base URL é normalizada antes do uso (`/v1`, `/v1/models` e `/v1/chat/completions` são aceitos sem duplicar o sufixo) — o `/chat/completions` duplicado era uma fonte de 404
+- **Fallback implacável**: `except Exception` captura tudo — HTTP 4xx/5xx, 404/410, timeout, rede e JSON inválido. O log registra exatamente `Erro na NVIDIA ({e}). Acionando Google Gemini...` e o próximo provedor assume na mesma iteração; a notícia é gerada sem tela de erro
+- **"Testar conexão" valida inferência real**: `POST /api/v1/llm/test` executa um `chat/completions` de verdade com `max_tokens=1` (não lista modelos). A string de erro do provedor volta no JSON para o frontend exibir; 404/410 marcam `degraded` com instrução de trocar de modelo
+- **Proxy de modelos reforçado**: `/configuracoes/llm/nvidia/models` normaliza a URL, distingue 401/403 (chave recusada) de outros erros e devolve `modelo_atual_disponivel`
+- **Frontend**: aviso vermelho quando o modelo selecionado saiu do catálogo da NVIDIA (404/410) — o usuário vê o problema antes de clicar em testar, com a indicação de que as gerações estão caindo no Gemini
+- **Teste funcional novo**: `backend/tests/test_llm_fallback.py` (13 verificações, roda sem pytest e sem servidor) cobre o fallback no 410, a mensagem de log exigida, o erro quando todos os provedores falham, o formato do `test_provider` e a normalização do endpoint — agregado ao CI
+- Colisão de versão resolvida por renumeração (0.4.06 já publicado), conforme a regra de sessões simultâneas do AGENTS.md
+
 ## 0.4.04 (2026-11-08)
 
 - **HOTFIX real — fim das janelas de CMD no instalador**: o 0.4.03 blindou apenas o launcher (`start.js`) e deixou o **caminho de instalação** descoberto. No Windows, `tar` (extração do Python portátil), `python -m venv` e `pip install -r requirements.txt` eram lançados **sem `windowsHide`** — era aí que as múltiplas janelas de terminal apareciam. Os três `spawnSync` de `scripts/install.js` agora nascem com `windowsHide: true` (`CREATE_NO_WINDOW`)
@@ -14,6 +27,11 @@ Todas as versões publicadas são registradas aqui antes do publish (regra em AG
 - **Guard verificado por mutação**: com a flag removida do `pip`, com um `subprocess.run` direto no backend e com `--reload` no uvicorn, o teste falha em todos os casos (exit 1) — não é carimbo de borracha
 - Nota de transparência: a colisão de versão com o 0.4.03 já publicado no registry foi resolvida por renumeração, conforme a regra de sessões simultâneas do AGENTS.md
 
+## 0.4.06 (2026-11-08)
+
+- Rótulos de exibição do LLM alinhados ao critério de aceitação: o provedor do Google passa a ser gravado/exposto como **`gemini`** em `noticias.llm_provider` (antes o id interno `google`), e os warning de fallback usam os nomines "NVIDIA NIM" e "Gemini" — `Modelo NVIDIA NIM indisponível (Status 404). Acionando fallback para Gemini.`
+- Nenhuma mudança funcional de roteamento — apenas nomenclatura consistente entre banco, log e UI
+
 ## 0.4.05 (2026-11-08)
 
 - **HOTFIX — fallback à prova de falhas no LLM Router** (crítico): roteamento reescrito em `backend/core/llm_router.py`, agora explícito provedor por provedor na ordem configurada. Qualquer erro HTTP (4xx/5xx, incluindo **404/410** da NVIDIA) é interceptado, registrado (`Modelo nvidia indisponível (Status {status}). Acionando fallback para {próximo}.`) e o próximo provedor é acionado imediatamente — a geração não trava mais. A função devolve qual provedor respondeu (`noticias.llm_provider`) e o incidente fica em `backend.log`

package/backend/app/main.py

@@ -31,7 +31,7 @@ async def lifespan(_: FastAPI):
     scheduler.parar()
 
 
-app = FastAPI(title="PandaNews API", version="0.4.5", lifespan=lifespan)
+app = FastAPI(title="PandaNews API", version="0.4.7", lifespan=lifespan)
 
 app.add_middleware(
     CORSMiddleware,

package/backend/app/routers/configuracoes.py

@@ -48,27 +48,52 @@ def listar_modelos_nvidia(db: Session = Depends(get_db)) -> dict:
     """Lista os modelos NVIDIA NIM disponíveis para a chave configurada.
 
     Proxy: a API key fica no banco local e nunca é exposta ao frontend.
-    Retorna 400 sem chave; 502 em falha de consulta.
+    Retorna 400 sem chave; 502 em falha de consulta. A Base URL é normalizada
+    pelo mesmo helper do Thunderbolt, então ``/v1``, ``/v1/models`` e
+    ``/v1/chat/completions`` são aceitos sem duplicar o sufixo.
     """
     import httpx
 
-    from backend.core.llm_router import provider_config
+    from backend.core.llm_router import _normalizar_base_url, provider_config
 
     cfg = provider_config(db, "nvidia")
     if not cfg["api_key"]:
         raise HTTPException(status_code=400, detail="API Key da NVIDIA não configurada — adicione-a antes de listar os modelos.")
-    url = cfg["base_url"].rstrip("/") + "/models"
+    base = _normalizar_base_url(cfg["base_url"])
+    if not base:
+        raise HTTPException(status_code=400, detail=f"Base URL da NVIDIA inválida: {cfg['base_url']!r}")
+    url = f"{base}/models"
     try:
-        resposta = httpx.get(url, headers={"Authorization": f"Bearer {cfg['api_key']}"}, timeout=20.0)
+        resposta = httpx.get(
+            url,
+            headers={"Accept": "application/json", "Authorization": f"Bearer {cfg['api_key']}"},
+            timeout=20.0,
+        )
     except httpx.HTTPError as exc:
         raise HTTPException(status_code=502, detail=f"Erro ao consultar a NVIDIA: {exc}") from exc
+    if resposta.status_code in (401, 403):
+        raise HTTPException(
+            status_code=502,
+            detail=f"A NVIDIA recusou a API key (HTTP {resposta.status_code}). Verifique a chave em Configurações.",
+        )
     if resposta.status_code != 200:
         raise HTTPException(
             status_code=502,
             detail=f"NVIDIA respondeu {resposta.status_code}: {resposta.text[:200]}",
         )
-    ids = sorted(str(m.get("id")) for m in resposta.json().get("data", []) if m.get("id"))
-    return {"models": ids, "modelo_atual": cfg["model"], "base_url": cfg["base_url"]}
+    try:
+        dados = resposta.json()
+    except ValueError as exc:
+        raise HTTPException(status_code=502, detail="A NVIDIA devolveu uma resposta que não é JSON.") from exc
+    ids = sorted(str(m.get("id")) for m in (dados.get("data") or []) if m.get("id"))
+    if not ids:
+        raise HTTPException(status_code=502, detail="A NVIDIA não devolveu nenhum modelo para esta chave.")
+    return {
+        "models": ids,
+        "modelo_atual": cfg["model"],
+        "base_url": cfg["base_url"],
+        "modelo_atual_disponivel": cfg["model"] in ids,
+    }
 
 
 @router.post("/testar-supabase")

package/backend/core/config.py

@@ -40,7 +40,12 @@ DEFAULT_LLM_BASE_URLS = {
     "nvidia": "https://integrate.api.nvidia.com/v1",
     "google": "https://generativelanguage.googleapis.com/v1beta/openai",
 }
+# Modelos precisam existir no catálogo do provedor. O default anterior da
+# NVIDIA (meta/llama-3.3-70b-instruct) chegou ao fim da vida em 2026-08-26 e
+# passou a devolver HTTP 410 "Gone" — o sintoma que o usuário via como 404.
+# `mistralai/mistral-large-2-instruct` está no catálogo atual (verificado
+# contra https://integrate.api.nvidia.com/v1/models).
 DEFAULT_LLM_MODELS = {
-    "nvidia": "meta/llama-3.3-70b-instruct",
+    "nvidia": "mistralai/mistral-large-2-instruct",
     "google": "gemini-3.8-flash",
 }

package/backend/core/llm_router.py

@@ -1,28 +1,86 @@
-"""Router de LLM do PandaNews: fallback ordenado e à prova de falhas.
+"""Router de LLM do PandaNews — réplica da integração NVIDIA do Thunderbolt.
 
-Roteamento explícito, provedor por provedor, na ordem configurada
-(padrão: NVIDIA NIM → Google Gemini). Qualquer erro HTTP do provedor atual
-(4xx/5xx — incluindo 404/410 de modelos descontinuados) é registrado e o
-próximo provedor é acionado imediatamente. A função devolve (texto, provedor)
-para registrar em noticias.llm_provider.
+O projeto Thunderbolt (referência que funciona) fala com provedores
+OpenAI-compatible — NVIDIA NIM, Gemini etc. — por **HTTP direto**:
+
+    POST {base_url}/chat/completions
+    Authorization: Bearer <api_key>
+    Content-Type:  application/json
+    {"model": ..., "messages": [...], "max_tokens": ..., "temperature": 0}
+
+Este módulo copia essa estrutura exata, trocando `requests` por `httpx` (já
+dependência do PandaNews). Nenhum SDK novo é necessário — em particular a
+biblioteca `openai` **não** é usada: ela não está declarada em
+requirements.txt, então instalá-la quebraria o backend com ImportError em
+toda instalação nova (foi exatamente o que derrubou o fluxo antes).
+
+Fallback implacável: qualquer exceção — HTTP 4xx/5xx (inclusive 404/410 de
+modelo descontinuado), timeout, erro de rede ou JSON inválido — é registrada e
+o próximo provedor da lista é acionado imediatamente. Nada escapa.
 """
 from __future__ import annotations
 
 import logging
-import time
+from urllib.parse import urlsplit, urlunsplit
 
 import httpx
-from openai import APIStatusError, OpenAI
 
 from backend.core.config import DEFAULT_LLM_BASE_URLS, DEFAULT_LLM_MODELS
 
 PROVEDORES = ("nvidia", "google")
 
+# Nomes exibidos no log — a mensagem de fallback usa estes rótulos.
+NOMES_PROVEDORES = {"nvidia": "NVIDIA", "google": "Google Gemini"}
+
+TIMEOUT_SEGUNDOS = 60.0
+
 # Logger filho do uvicorn.error: mensagens vão para o backend.log (e stderr),
 # com a disciplina de logs do servidor.
 logger = logging.getLogger("uvicorn.error.pandanews")
 
 
+# --------------------------------------------------------------- endpoints
+
+def _normalizar_base_url(base_url: str) -> str:
+    """Mantém apenas esquema/host/path da Base URL (como o Thunderbolt).
+
+    Aceita tanto ``https://host/v1`` quanto ``https://host/v1/models`` ou
+    ``https://host/v1/chat/completions`` — o sufixo é descartado/refeito,
+    evitando o ``/chat/completions`` duplicado que provocaria 404.
+    """
+    raw = str(base_url or "").strip()
+    if not raw:
+        return ""
+    try:
+        parsed = urlsplit(raw)
+    except ValueError:
+        return raw.rstrip("/")
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        return raw.rstrip("/")
+    path = parsed.path.rstrip("/")
+    for sufixo in ("/chat/completions", "/models"):
+        if path.endswith(sufixo):
+            path = path[: -len(sufixo)]
+            break
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+
+def chat_completions_endpoint(base_url: str) -> str:
+    """Endpoint de Chat Completions — igual ao do Thunderbolt."""
+    base = _normalizar_base_url(base_url)
+    return f"{base}/chat/completions" if base else ""
+
+
+def _headers(api_key: str) -> dict:
+    """Cabeçalhos OpenAI-compatible do Thunderbolt (Accept incluído)."""
+    headers = {"Accept": "application/json", "Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+# ------------------------------------------------------------- acesso a config
+
 def get_config(db, chave: str, padrao: str = "") -> str:
     from backend.core.database import Configuracao
 
@@ -38,25 +96,55 @@ def provider_config(db, provider: str) -> dict:
     }
 
 
-def _chamar_provedor(db, provider: str, prompt: str, max_tokens: int) -> tuple[str, str]:
-    """Uma chamada de chat completion no provedor. Levanta em caso de erro."""
+# ---------------------------------------------------------- chamada ao provedor
+
+def chamar_provedor(db, provider: str, prompt: str, max_tokens: int) -> tuple[str, str]:
+    """Uma chamada de chat completion no provedor. Levanta em caso de erro.
+
+    Cópia da estrutura do Thunderbolt: POST HTTP direto no endpoint
+    ``{base_url}/chat/completions`` com Bearer token. Qualquer resposta >= 400
+    levanta ``httpx.HTTPStatusError`` — capturada pelo fallback em
+    ``gerar_texto``.
+    """
     cfg = provider_config(db, provider)
-    client = OpenAI(api_key=cfg["api_key"], base_url=cfg["base_url"], timeout=60.0)
-    resposta = client.chat.completions.create(
-        model=cfg["model"],
-        messages=[{"role": "user", "content": prompt}],
-        max_tokens=max_tokens,
-    )
-    texto = resposta.choices[0].message.content or ""
-    modelo = str(getattr(resposta, "model", "") or cfg["model"])
+    if not cfg["api_key"]:
+        raise RuntimeError(f"{NOMES_PROVEDORES.get(provider, provider)}: API key não configurada.")
+    if not cfg["model"]:
+        raise RuntimeError(f"{NOMES_PROVEDORES.get(provider, provider)}: nenhum modelo configurado.")
+
+    endpoint = chat_completions_endpoint(cfg["base_url"])
+    if not endpoint:
+        raise RuntimeError(f"{NOMES_PROVEDORES.get(provider, provider)}: Base URL inválida ({cfg['base_url']!r}).")
+
+    payload = {
+        "model": cfg["model"],
+        "messages": [{"role": "user", "content": prompt}],
+        "temperature": 0.7,
+        "max_tokens": max_tokens,
+    }
+
+    with httpx.Client(timeout=TIMEOUT_SEGUNDOS) as client:
+        resposta = client.post(endpoint, headers=_headers(cfg["api_key"]), json=payload)
+        resposta.raise_for_status()
+        dados = resposta.json()
+
+    texto = ""
+    escolhas = dados.get("choices") or []
+    if escolhas:
+        texto = (escolhas[0].get("message") or {}).get("content") or ""
+    if not texto:
+        raise RuntimeError(f"{NOMES_PROVEDORES.get(provider, provider)}: resposta sem conteúdo.")
+
+    modelo = str(dados.get("model") or cfg["model"])
     return texto, modelo
 
 
 def gerar_texto(db, prompt: str, max_tokens: int = 1024) -> tuple[str, str]:
     """Gera texto com fallback ordenado. Retorna (texto, provedor_que_respondeu).
 
-    Se um provedor falhar por qualquer erro HTTP, registra o incidente e
-    aciona o próximo da lista. Só levanta erro quando TODOS falham.
+    Fallback implacável: capture ``Exception`` — não importa se é HTTP 404/410
+    (modelo descontinuado), 500, timeout ou queda de rede. O incidente é
+    registrado e o próximo provedor é acionado na mesma iteração.
     """
     ordem = [p.strip() for p in get_config(db, "llm_fallback_ordem", "nvidia,google").split(",") if p.strip()]
     disponiveis = [p for p in ordem if p in PROVEDORES and provider_config(db, p)["api_key"]]
@@ -65,67 +153,100 @@ def gerar_texto(db, prompt: str, max_tokens: int = 1024) -> tuple[str, str]:
 
     ultimo_erro: Exception | None = None
     for indice, provider in enumerate(disponiveis):
+        nome = NOMES_PROVEDORES.get(provider, provider)
         proximo = disponiveis[indice + 1] if indice + 1 < len(disponiveis) else None
+        nome_proximo = NOMES_PROVEDORES.get(proximo, proximo) if proximo else "nenhum provedor"
+
         try:
-            texto, modelo = _chamar_provedor(db, provider, prompt, max_tokens)
-            logger.info("LLM: %s respondeu (modelo %s)", provider, modelo)
+            texto, modelo = chamar_provedor(db, provider, prompt, max_tokens)
+            logger.info("LLM: %s respondeu (modelo %s)", nome, modelo)
             return texto, provider
-        except APIStatusError as exc:
-            status = exc.status_code
-            ultimo_erro = exc
-            logger.warning("LLM: %s falhou com HTTP %s (%s)", provider, status, str(exc)[:300])
-            if status in (404, 410):
-                destino = proximo or "nenhum"
-                logger.warning(
-                    "Modelo %s indisponível (Status %s). Acionando fallback para %s.",
-                    provider,
-                    status,
-                    destino,
-                )
-        except Exception as exc:  # noqa: BLE001 — timeouts, rede, auth: tenta o próximo
+
+        except Exception as exc:  # noqa: BLE001 — fallback implacável: TUDO troca de provedor
             ultimo_erro = exc
-            logger.warning("LLM: %s falhou (%s): %s", provider, type(exc).__name__, str(exc)[:300])
-        if proximo:
-            continue
-    raise RuntimeError(f"Todos os provedores de LLM falharam ({', '.join(disponiveis)}). Último erro: {ultimo_erro}")
+            if proximo:
+                logger.warning("Erro na %s (%s). Acionando %s...", nome, exc, nome_proximo)
+            else:
+                logger.warning("Erro na %s (%s). Sem provedor restante no fallback.", nome, exc)
+
+    raise RuntimeError(
+        f"Todos os provedores de LLM falharam ({', '.join(disponiveis)}). Último erro: {ultimo_erro}"
+    )
+
 
+# ------------------------------------------------------------ teste de conexão
 
 def test_provider(db, provider: str) -> dict:
-    """Chamada real e curta (POST /chat/completions) para validar a chave.
+    """Teste REAL de conexão: uma chamada de inferência com 1 token.
+
+    Igual ao ``validate_openai_compatible_api_key`` do Thunderbolt — não lista
+    modelos, executa um POST mínimo em ``/chat/completions``. A string de erro
+    do provedor volta no JSON para o frontend exibir na tela.
 
-    404/410 → 'degraded': a chave pode funcionar, mas o modelo endpoint está
-    indisponível — o pipeline segue pelo fallback. A UI distingue os estados.
+    404/410 → ``degraded``: a chave pode ser válida, mas o modelo saiu do
+    catálogo — o pipeline segue pelo fallback sem travar a tela.
     """
     if provider not in PROVEDORES:
         return {"ok": False, "detail": f"Provedor desconhecido: {provider}"}
     cfg = provider_config(db, provider)
     if not cfg["api_key"]:
         return {"ok": False, "detail": "API key não configurada — adicione em Configurações."}
-    url = cfg["base_url"].rstrip("/") + "/chat/completions"
+    if not cfg["model"]:
+        return {"ok": False, "detail": "Nenhum modelo configurado — selecione um antes de testar."}
+
+    endpoint = chat_completions_endpoint(cfg["base_url"])
+    if not endpoint:
+        return {"ok": False, "detail": f"Base URL inválida: {cfg['base_url']!r}"}
+
     payload = {
         "model": cfg["model"],
-        "messages": [{"role": "user", "content": "Responda apenas: ok"}],
-        "max_tokens": 5,
+        "messages": [{"role": "user", "content": "Responda apenas OK."}],
+        "max_tokens": 1,
+        "temperature": 0,
     }
-    headers = {"Authorization": f"Bearer {cfg['api_key']}", "Content-Type": "application/json"}
-    started = time.perf_counter()
+
     try:
-        resp = httpx.post(url, json=payload, headers=headers, timeout=20.0)
-        elapsed_ms = int((time.perf_counter() - started) * 1000)
-        if resp.status_code == 200:
-            return {"ok": True, "status": 200, "latency_ms": elapsed_ms, "model": cfg["model"], "base_url": cfg["base_url"]}
-        if resp.status_code in (404, 410):
-            return {
-                "ok": False,
-                "degraded": True,
-                "status": resp.status_code,
-                "detail": (
-                    f"Sua chave da NVIDIA retornou erro {resp.status_code}. "
-                    "O sistema usará o Gemini (fallback) para gerar as notícias."
-                    if provider == "nvidia"
-                    else f"Endpoint do Gemini retornou {resp.status_code}. O sistema usará a NVIDIA (primário) para gerar as notícias."
-                ),
-            }
-        return {"ok": False, "status": resp.status_code, "detail": resp.text[:400]}
-    except Exception as exc:  # noqa: BLE001
-        return {"ok": False, "detail": f"{type(exc).__name__}: {exc}"}
+        with httpx.Client(timeout=20.0) as client:
+            resp = client.post(endpoint, headers=_headers(cfg["api_key"]), json=payload)
+    except httpx.HTTPError as exc:
+        return {"ok": False, "detail": f"Não foi possível testar {endpoint}: {exc}"}
+
+    elapsed_ms = int(resp.elapsed.total_seconds() * 1000)
+
+    if resp.status_code in (401, 403):
+        return {
+            "ok": False,
+            "status": resp.status_code,
+            "detail": f"O endpoint recusou a API key (HTTP {resp.status_code}). Verifique a chave em Configurações.",
+        }
+    if resp.status_code in (404, 410):
+        return {
+            "ok": False,
+            "degraded": True,
+            "status": resp.status_code,
+            "detail": (
+                f"Modelo '{cfg['model']}' indisponível na NVIDIA (HTTP {resp.status_code}): "
+                f"{resp.text[:200]} — use o botão ↻ para escolher um modelo do catálogo. "
+                "As notícias seguem sendo geradas pelo Gemini (fallback)."
+                if provider == "nvidia"
+                else (
+                    f"Modelo '{cfg['model']}' indisponível no Gemini (HTTP {resp.status_code}): "
+                    f"{resp.text[:200]} — as notícias seguem sendo geradas pela NVIDIA (primário)."
+                )
+            ),
+        }
+    if resp.status_code >= 400:
+        return {
+            "ok": False,
+            "status": resp.status_code,
+            "detail": f"O endpoint de teste devolveu HTTP {resp.status_code}: {resp.text[:400]}",
+        }
+
+    return {
+        "ok": True,
+        "status": 200,
+        "latency_ms": elapsed_ms,
+        "model": cfg["model"],
+        "base_url": cfg["base_url"],
+        "endpoint": endpoint,
+    }

package/backend/tests/test_llm_fallback.py

@@ -0,0 +1,216 @@
+"""Teste funcional do fallback implacável do router de LLM.
+
+Roda sem pytest e sem servidor: `python backend/tests/test_llm_fallback.py`.
+
+Cobre exatamente o que a correção promete:
+  1. NVIDIA devolve HTTP 410 (modelo em fim de vida) -> o Gemini assume,
+     sem exceção vazando para o pipeline.
+  2. A mensagem de log é a pedida: "Erro na NVIDIA (...). Acionando Google
+     Gemini..."
+  3. Todos os provedores falhando -> RuntimeError clara (não silenciosa).
+  4. `test_provider` devolve a string de erro do provedor ( HTTP 410/404 ),
+     marcando `degraded`, para o frontend exibir.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+from datetime import timedelta as _timedelta
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT))
+
+# O teste não precisa de banco: `llm_router.get_config` importa
+# `backend.core.database` de forma preguiçosa (dentro da função), o que
+# exigiria SQLAlchemy só para rodar os assertions. Um stub do módulo mantém
+# o teste autônomo — sem servidor, sem pytest, sem dependências extras.
+import types  # noqa: E402
+
+if "backend.core.database" not in sys.modules:
+    _stub = types.ModuleType("backend.core.database")
+
+    class _ConfiguracaoStub:  # noqa: D401 - apenas um marcador para o .get()
+        """Stub: o FakeDB abaixo responde ao `.get()` sem tocar no ORM."""
+
+    _stub.Configuracao = _ConfiguracaoStub
+    sys.modules["backend.core.database"] = _stub
+
+from backend.core import llm_router  # noqa: E402
+
+
+class _Row:
+    def __init__(self, valor: str) -> None:
+        self.valor = valor
+
+
+class FakeDB:
+    """Banco mínimo: só o que provider_config()/get_config() precisam."""
+
+    def __init__(self, valores: dict[str, str]) -> None:
+        self.valores = valores
+
+    def get(self, _modelo, chave: str):
+        return _Row(self.valores[chave]) if chave in self.valores else None
+
+
+def _db_com_chaves() -> FakeDB:
+    return FakeDB(
+        {
+            "nvidia_api_key": "nv-test",
+            "nvidia_model": "meta/llama-3.3-70b-instruct",  # EOL de propósito
+            "google_api_key": "go-test",
+            "google_model": "gemini-3.8-flash",
+            "llm_fallback_ordem": "nvidia,google",
+        }
+    )
+
+
+falhas: list[str] = []
+
+
+def check(condicao: bool, mensagem: str) -> None:
+    print(f"{'PASS' if condicao else 'FAIL'} — {mensagem}")
+    if not condicao:
+        falhas.append(mensagem)
+
+
+# ------------------------------------------------------- 1) fallback no 410
+
+class _Resposta410:
+    """Simula httpx.HTTPStatusError do raise_for_status() num 410."""
+
+    status_code = 410
+
+
+def _chamar_nvidia_410(db, provider, prompt, max_tokens):
+    if provider == "nvidia":
+        raise RuntimeError("410 Gone: modelo 'meta/llama-3.3-70b-instruct' chegou ao fim da vida")
+    return "noticia gerada pelo gemini", "gemini-3.8-flash"
+
+
+original_chamar = llm_router.chamar_provedor
+llm_router.chamar_provedor = _chamar_nvidia_410
+
+registros: list[str] = []
+
+
+class _Capturador(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        registros.append(record.getMessage())
+
+
+llm_router.logger.addHandler(_Capturador())
+llm_router.logger.setLevel(logging.INFO)
+
+texto, provedor = llm_router.gerar_texto(_db_com_chaves(), "escreva uma noticia")
+
+check(provedor == "google", "NVIDIA com 410 -> o Gemini assume (provedor devolvido: google)")
+check("noticia gerada pelo gemini" in texto, "o texto devolvido é o do Gemini, não uma exceção")
+
+mensagem_esperada = "Erro na NVIDIA (410 Gone"
+check(
+    any(mensagem_esperada in m and "Acionando Google Gemini" in m for m in registros),
+    f"log no formato pedido: 'Erro na NVIDIA ({{e}}). Acionando Google Gemini...' — obtido: {registros}",
+)
+
+# --------------------------------------------- 2) todos falham -> erro claro
+
+def _chamar_todos_falham(db, provider, prompt, max_tokens):
+    raise RuntimeError(f"{provider} fora do ar")
+
+
+llm_router.chamar_provedor = _chamar_todos_falham
+try:
+    llm_router.gerar_texto(_db_com_chaves(), "prompt")
+    check(False, "todos os provedores falhando devolve RuntimeError")
+except RuntimeError as exc:
+    check(
+        "Todos os provedores de LLM falharam" in str(exc),
+        "todos os provedores falhando -> RuntimeError clara (sem silêncio)",
+    )
+
+llm_router.chamar_provedor = original_chamar
+
+# ------------------------------------------- 3) test_provider devolve o erro
+
+class _FakeResponse:
+    def __init__(self, status_code: int, texto: str) -> None:
+        self.status_code = status_code
+        self.text = texto
+        self.elapsed = _timedelta(milliseconds=42)
+
+
+def _testar_com_resposta(status_code: int, texto: str) -> dict:
+    class _ClientFake:
+        def __init__(self, *a, **k) -> None:
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def post(self, *a, **k):
+            return _FakeResponse(status_code, texto)
+
+    llm_router.httpx.Client = _ClientFake
+    return llm_router.test_provider(_db_com_chaves(), "nvidia")
+
+
+resultado_410 = _testar_com_resposta(
+    410, '{"detail":"The model has reached its end of life"}'
+)
+check(resultado_410["ok"] is False, "test_provider: HTTP 410 -> ok=False")
+check(resultado_410.get("degraded") is True, "test_provider: HTTP 410 -> degraded=True (fallback avisa)")
+check(
+    "fim da vida" in resultado_410["detail"] or "410" in resultado_410["detail"],
+    "test_provider: a string de erro do provedor volta no JSON para a tela",
+)
+
+resultado_401 = _testar_com_resposta(401, "unauthorized")
+check(
+    "recusou a API key" in resultado_401["detail"],
+    "test_provider: HTTP 401 -> mensagem de credencial explícita",
+)
+
+resultado_500 = _testar_com_resposta(500, "internal error")
+check(
+    "HTTP 500" in resultado_500["detail"],
+    "test_provider: HTTP 500 -> código e corpo devolvidos ao frontend",
+)
+
+# ------------------------------------------- 4) endpoint replicado do Thunderbolt
+
+check(
+    llm_router.chat_completions_endpoint("https://integrate.api.nvidia.com/v1")
+    == "https://integrate.api.nvidia.com/v1/chat/completions",
+    "endpoint: base '/v1' -> '/v1/chat/completions' (igual ao Thunderbolt)",
+)
+check(
+    llm_router.chat_completions_endpoint("https://integrate.api.nvidia.com/v1/models")
+    == "https://integrate.api.nvidia.com/v1/chat/completions",
+    "endpoint: base com '/models' não duplica o sufixo (evita 404)",
+)
+check(
+    llm_router.chat_completions_endpoint("https://integrate.api.nvidia.com/v1/chat/completions")
+    == "https://integrate.api.nvidia.com/v1/chat/completions",
+    "endpoint: base já com '/chat/completions' não duplica (evita 404)",
+)
+headers = llm_router._headers("chave-abc")
+check(
+    headers.get("Authorization") == "Bearer chave-abc"
+    and headers.get("Content-Type") == "application/json"
+    and headers.get("Accept") == "application/json",
+    "headers OpenAI-compatible: Bearer + Content-Type + Accept (como o Thunderbolt)",
+)
+
+# ------------------------------------------------------------- veredicto
+
+print()
+if falhas:
+    print(f"Fallback do router LLM: {len(falhas)} verificação(ões) falharam.")
+    sys.exit(1)
+print("Fallback do router LLM: todas as verificações passaram.")
+sys.exit(0)