multi-key failover + grounding + isolation

app/config.py

@@ -15,8 +15,9 @@ class Settings(BaseSettings):
     database_url: str = "sqlite+aiosqlite://"
     testing: bool = False
 
-    # LLM: Groq (primary)
+    # LLM: Groq (primary). Multiple keys for redundancy: GROQ_API_KEYS=k1,k2,k3
     groq_api_key: str = ""
+    groq_api_keys: Annotated[list[str], NoDecode] = []
     groq_base_url: str = "https://api.groq.com/openai/v1"
     # gpt-oss-120b: stable on Groq + reliable tool calling (Llama 3.3 70B
     # intermittently returns tool_use_failed on Groq).
@@ -67,7 +68,7 @@ class Settings(BaseSettings):
     smtp_password: str = ""
     smtp_from: str = ""
 
-    @field_validator("llm_provider_order", "allowed_origins", mode="before")
+    @field_validator("llm_provider_order", "allowed_origins", "groq_api_keys", mode="before")
     @classmethod
     def _split_csv(cls, v: object) -> object:
         if isinstance(v, str):

app/llm/base.py

@@ -50,6 +50,8 @@ class ChatResult:
     content: str | None
     tool_calls: list[ToolCall] = field(default_factory=list)
     finish_reason: str | None = None
+    usage: dict[str, int] = field(default_factory=dict)  # prompt/completion/total tokens
+    provider: str | None = None
 
 
 class LLMProvider(Protocol):
@@ -81,10 +83,17 @@ def parse_openai_choice(data: dict[str, Any]) -> ChatResult:
         calls.append(
             ToolCall(id=c.get("id", ""), name=fn.get("name", ""), arguments=args or {})
         )
+    raw_usage = data.get("usage") or {}
+    usage = {
+        "prompt_tokens": int(raw_usage.get("prompt_tokens") or 0),
+        "completion_tokens": int(raw_usage.get("completion_tokens") or 0),
+        "total_tokens": int(raw_usage.get("total_tokens") or 0),
+    }
     return ChatResult(
         content=msg.get("content"),
         tool_calls=calls,
         finish_reason=choice.get("finish_reason"),
+        usage=usage,
     )
 
 

app/llm/router.py

@@ -45,12 +45,14 @@ class LLMRouter:
             if not model:
                 continue
             try:
-                return await provider.chat(
+                result = await provider.chat(
                     messages=messages,
                     tools=tools,
                     model=model,
                     temperature=self.temperature if temperature is None else temperature,
                 )
+                result.provider = name
+                return result
             except ProviderError as exc:
                 log.warning("LLM provider %s failed (%s); failing over", name, exc)
                 last_exc = exc
@@ -59,28 +61,37 @@ class LLMRouter:
 
 
 def build_router_from_settings(settings: Any) -> LLMRouter:
-    """Construct an LLMRouter from Settings, including only configured providers."""
+    """Build an LLMRouter with one entry PER Groq key (redundancy) + Cloudflare.
+
+    The router tries each in order and fails over on any error, so as long as a
+    single key/provider is healthy the bot answers. Add keys via GROQ_API_KEYS.
+    """
     from app.llm.cloudflare import CloudflareProvider
     from app.llm.groq import GroqProvider
 
     providers: dict[str, LLMProvider] = {}
     models: dict[str, dict[str, str]] = {}
+    order: list[str] = []
 
-    if settings.groq_api_key:
-        providers["groq"] = GroqProvider(
-            api_key=settings.groq_api_key, base_url=settings.groq_base_url
-        )
-        models["groq"] = {"small": settings.model_small, "large": settings.model_large}
+    # Collect Groq keys (single + list), de-duplicated, preserving order.
+    groq_keys: list[str] = []
+    for key in [settings.groq_api_key, *settings.groq_api_keys]:
+        key = (key or "").strip()
+        if key and key not in groq_keys:
+            groq_keys.append(key)
+
+    for i, key in enumerate(groq_keys):
+        name = f"groq{i}"
+        providers[name] = GroqProvider(api_key=key, base_url=settings.groq_base_url)
+        models[name] = {"small": settings.model_small, "large": settings.model_large}
+        order.append(name)
 
     if settings.cloudflare_account_id and settings.cloudflare_api_token:
         providers["cloudflare"] = CloudflareProvider(
             account_id=settings.cloudflare_account_id,
             api_token=settings.cloudflare_api_token,
         )
-        models["cloudflare"] = {
-            "small": settings.cf_model_small,
-            "large": settings.cf_model_large,
-        }
+        models["cloudflare"] = {"small": settings.cf_model_small, "large": settings.cf_model_large}
+        order.append("cloudflare")
 
-    order = [p for p in settings.llm_provider_order if p in providers]
     return LLMRouter(providers=providers, order=order, models=models)

app/orchestrator.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import logging
 from typing import Any
 
 from sqlalchemy import select
@@ -14,6 +15,8 @@ from app.schemas import ChatResponse
 from app.tools import registry
 from app.tools.registry import ToolContext
 
+log = logging.getLogger(__name__)
+
 HISTORY_LIMIT = 10
 MAX_TOOL_ITERS = 4
 FALLBACK_REPLY = "Lo siento, ahora mismo no he podido completar la consulta. ¿Puedes reformularla?"
@@ -60,19 +63,26 @@ async def run_turn(
 
     used_tools: list[str] = []
     reply = FALLBACK_REPLY
+    total_tokens = 0
+    provider_used: str | None = None
 
     async def _chat(tools):
         """Resilient call: if tool-calling fails (e.g. Groq tool_use_failed) or a
         provider errors, degrade to a no-tools answer so we never 500."""
+        nonlocal total_tokens, provider_used
+        result = None
         try:
-            return await router.chat(messages=messages, tools=tools, tier="large")
+            result = await router.chat(messages=messages, tools=tools, tier="large")
         except ProviderError:
-            if not tools:
-                return None
-            try:
-                return await router.chat(messages=messages, tools=[], tier="large")
-            except ProviderError:
-                return None
+            if tools:
+                try:
+                    result = await router.chat(messages=messages, tools=[], tier="large")
+                except ProviderError:
+                    result = None
+        if result is not None:
+            total_tokens += result.usage.get("total_tokens", 0)
+            provider_used = result.provider or provider_used
+        return result
 
     for _ in range(MAX_TOOL_ITERS):
         result = await _chat(registry.specs())
@@ -108,6 +118,11 @@ async def run_turn(
     ctx.db.add(ChatMessage(session_id=ctx.session.id, role="assistant", content=reply))
     await ctx.db.flush()
 
+    log.info(
+        "chat turn tenant=%s provider=%s tools=%s tokens=%s",
+        ctx.tenant_id, provider_used, used_tools, total_tokens,
+    )
+
     return ChatResponse(
         session_id=ctx.session.id, reply=reply, lang=ctx.session.lang, used_tools=used_tools
     )

app/prompts.py

@@ -3,36 +3,47 @@
 
 from __future__ import annotations
 
-SYSTEM_TEMPLATE = """Eres {brand_name}, el asistente virtual de atención al cliente de la tienda.
+SYSTEM_TEMPLATE = """Eres {brand_name}, asistente virtual de atención al cliente de esta tienda online. Tu trabajo es ayudar a los clientes de forma precisa, cercana y útil, SIEMPRE basándote en datos reales de la tienda.
 
 ## Idioma
-- Responde SIEMPRE en el mismo idioma en el que te escribe el cliente (detéctalo del último mensaje).
-- Si el cliente escribe en portugués, usa portugués de Portugal (pt-PT).
+- Responde SIEMPRE en el mismo idioma del último mensaje del cliente (español, portugués de Portugal pt-PT, inglés, etc.). Si cambia de idioma, cámbialo tú también.
 
-## Herramientas (úsalas SIEMPRE para datos reales)
-- `search_knowledge`: información de la tienda y productos (fichas, PDFs, web). Úsala para dudas de información, especificaciones, políticas, envíos, etc.
-- `search_products`: catálogo en vivo (precios y disponibilidad).
+## Cómo trabajas (lee bien y usa las herramientas SIEMPRE)
+Tienes estas herramientas y DEBES usarlas para cualquier dato; nunca respondas de memoria:
+- `search_knowledge`: base de conocimiento de la tienda (catálogo, fichas técnicas, PDFs, páginas web, políticas). Úsala para CUALQUIER duda de información: qué venden, especificaciones, materiales, medidas, usos, compatibilidad, instrucciones, garantía, envíos, devoluciones, pagos, datos de la empresa, recomendaciones, comparativas, etc.
+- `search_products`: catálogo en vivo (precio y disponibilidad reales).
 - `lookup_order`: estado y seguimiento de un pedido.
-
-## REGLA DE ORO — no inventes NADA
-- Responde ÚNICAMENTE con información que aparezca en los resultados de las herramientas.
-- NO inventes ni modifiques especificaciones, medidas, temperaturas, materiales, precios, plazos ni nombres de productos. Copia los datos TAL CUAL aparecen (p.ej. si pone "-10 ºC a +60 ºC", no digas otra cosa).
-- Si un dato concreto NO está en los resultados, dilo con honestidad ("no tengo ese dato a mano") y ofrece consultarlo o pasar la consulta al equipo. NUNCA rellenes huecos con conocimiento general.
-- Si no encuentras nada relevante, no te inventes un catálogo: pide más detalle o deriva al equipo.
-
-## Pedidos (privacidad + detección flexible)
-- Para localizar un pedido necesitas el **email** del cliente y **UN segundo dato** que lo identifique. Acepta cualquiera de estos como segundo dato: **número de pedido**, **código postal** del envío, o **nombre y apellidos**.
-- Pide el email y ese segundo dato de forma natural; NO exijas el número de pedido si el cliente te da el código postal o el nombre. Pasa a `lookup_order` lo que tengas (email + lo que haya dado).
+- `escalate_to_human`: pasar la consulta al equipo humano.
+
+Reglas de uso:
+1. Ante CUALQUIER pregunta de información o producto, llama PRIMERO a `search_knowledge` (y a `search_products` si preguntan precio o disponibilidad). Si la pregunta toca varios temas, haz varias búsquedas con términos distintos hasta tener la información.
+2. LEE con atención TODO lo que devuelven las herramientas antes de responder y usa todos los detalles relevantes.
+3. Reformula la búsqueda si la primera no trae lo que necesitas (prueba sinónimos o palabras clave del producto).
+
+## REGLA DE ORO — exactitud, cero invención
+- Responde ÚNICAMENTE con lo que aparezca en los resultados de las herramientas. Copia los datos TAL CUAL (cifras, medidas, temperaturas, materiales, precios, nombres de producto). Si la ficha dice "-10 ºC a +60 ºC", di exactamente eso.
+- Si un dato concreto NO está en los resultados, dilo con honestidad ("no tengo ese dato exacto a mano") y ofrece consultarlo con el equipo. NUNCA rellenes huecos con conocimiento general ni te inventes productos, precios o especificaciones.
+- Para recomendaciones o comparativas, básate SOLO en los productos/datos recuperados. Si falta información, pregunta o deriva al equipo.
+
+## Tipos de pregunta (sirve para cualquiera)
+- Pregunta concreta (un dato): da el dato exacto del documento.
+- Pregunta amplia o vaga ("¿qué vendéis?", "ayuda"): busca y da un resumen claro de las categorías/productos principales reales, y ofrece profundizar.
+- Precio/stock: usa `search_products` y da precio y disponibilidad reales (con enlace si lo hay).
+- Varias preguntas a la vez: responde a cada parte.
+- Fuera de tema (no es de la tienda): redirige con amabilidad hacia cómo puedes ayudar con la tienda y sus productos.
+
+## Pedidos (privacidad + verificación flexible)
+- Para localizar un pedido necesitas el **email** del cliente y **UN segundo dato** identificativo. Acepta cualquiera: **número de pedido**, **código postal** del envío, o **nombre y apellidos**. NO exijas el número de pedido si te dan el código postal o el nombre.
+- Pasa a `lookup_order` el email y el segundo dato que te haya dado.
 - Revela ÚNICAMENTE el estado del envío y el seguimiento (transportista, número, enlace, fecha estimada). NUNCA reveles la dirección completa ni datos de pago.
-- Si la verificación falla, di de forma genérica que no has podido localizar el pedido con esos datos y pide que los revise. NO digas qué campo es incorrecto.
-- Tras varios intentos fallidos queda bloqueado temporalmente; pide que lo intente más tarde.
+- Si no se localiza, dilo de forma genérica ("no he podido localizar un pedido con esos datos, revísalos por favor") sin decir qué campo falla. Tras varios intentos queda bloqueado un rato.
 
 ## Honestidad y escalado
-- Si no sabes algo o no puedes resolverlo, dilo con honestidad y ofrece pasar la consulta al equipo humano: pide el email del cliente y usa `escalate_to_human`.
+- Si no puedes resolver algo, sé honesto y ofrece pasar la consulta al equipo: pide el email del cliente y usa `escalate_to_human`.
 
 ## Tono y formato
-- Cercano, profesional y útil. Respuestas claras y al grano.
-- El chat es estrecho: NO uses tablas. Usa frases breves o listas con guiones "-". Resalta lo clave con **negrita**.
+- Cercano, profesional y resolutivo.
+- El chat es estrecho: NO uses tablas. Usa frases breves o listas con guiones "-", y resalta lo clave con **negrita**. Respuestas claras y al grano.
 """
 
 

app/tools/knowledge_tool.py

@@ -14,7 +14,7 @@ async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
     query = (args.get("query") or "").strip()
     if not query:
         return {"context": "", "sources": [], "note": "empty query"}
-    results = await index.search(ctx.db, query, k=4, tenant_id=ctx.tenant_id)
+    results = await index.search(ctx.db, query, k=6, tenant_id=ctx.tenant_id)
     if not results:
         return {"context": "", "sources": [], "note": "no relevant information found"}
     blocks = []

app/tools/order_tool.py

@@ -43,7 +43,8 @@ async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
         }
 
     limiter = get_order_limiter()
-    if not limiter.allow(email.lower(), ctx.now):
+    rl_key = f"{ctx.tenant_id}:{email.lower()}"  # per-tenant so stores don't affect each other
+    if not limiter.allow(rl_key, ctx.now):
         return {"status": "locked"}
 
     try:
@@ -66,5 +67,5 @@ async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
     if not result.ok or result.matched is None:
         return {"status": "not_found"}
 
-    limiter.reset(email.lower())
+    limiter.reset(rl_key)
     return {"status": "verified", "tracking": parse_tracking(result.matched)}

tests/llm/test_groq.py

@@ -61,6 +61,22 @@ async def test_groq_parses_tool_calls():
     assert r.tool_calls[0].arguments == {"email": "a@b.c"}
 
 
+@respx.mock
+async def test_groq_captures_token_usage():
+    respx.post(URL).mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "choices": [{"finish_reason": "stop", "message": {"content": "ok"}}],
+                "usage": {"prompt_tokens": 120, "completion_tokens": 30, "total_tokens": 150},
+            },
+        )
+    )
+    r = await _provider().chat(messages=[{"role": "user", "content": "x"}], tools=[], model="m")
+    assert r.usage["total_tokens"] == 150
+    assert r.usage["prompt_tokens"] == 120
+
+
 @respx.mock
 async def test_groq_429_raises_ratelimit():
     respx.post(URL).mock(return_value=httpx.Response(429, text="slow down"))

tests/llm/test_router.py

@@ -53,6 +53,34 @@ async def test_router_failover_on_ratelimit():
     assert cf.last_model == "cs"
 
 
+def test_build_router_multiple_groq_keys_and_cloudflare():
+    from types import SimpleNamespace
+
+    from app.llm.router import build_router_from_settings
+
+    s = SimpleNamespace(
+        groq_api_key="k1",
+        groq_api_keys=["k2", "k3", "k1"],  # k1 deduped
+        groq_base_url="https://api.groq.com/openai/v1",
+        model_small="s",
+        model_large="l",
+        cloudflare_account_id="acct",
+        cloudflare_api_token="tok",
+        cf_model_small="cs",
+        cf_model_large="cl",
+    )
+    router = build_router_from_settings(s)
+    assert router.order == ["groq0", "groq1", "groq2", "cloudflare"]  # 3 keys + CF
+    assert len(router.providers) == 4
+
+
+async def test_router_tags_provider_name():
+    groq = FakeProvider(result=ChatResult(content="ok", tool_calls=[], finish_reason="stop"))
+    router = LLMRouter(providers={"groq0": groq}, order=["groq0"], models={"groq0": {"large": "l"}})
+    r = await router.chat(messages=[{"role": "user", "content": "x"}], tools=[], tier="large")
+    assert r.provider == "groq0"
+
+
 async def test_router_raises_when_all_fail():
     groq = FakeProvider(raise_exc=ProviderError("g"))
     cf = FakeProvider(raise_exc=ProviderError("c"))

tests/test_multitenant.py

@@ -81,6 +81,42 @@ async def test_create_tenant_encrypts_secret(db_session):
     assert tenant_shopify_client(plain) is None
 
 
+async def test_order_lockout_is_per_tenant(db_session):
+    """A spammed email in tenant A must not lock that email in tenant B."""
+    from app.models import ChatSession, Tenant
+    from app.tools import order_tool
+    from app.tools.registry import ToolContext
+
+    a = Tenant(slug="ta")
+    b = Tenant(slug="tb")
+    db_session.add_all([a, b])
+    await db_session.flush()
+
+    class FakeShopify:
+        async def execute(self, query, variables=None):
+            return {"orders": {"edges": []}}  # no match -> failed attempts
+
+    from app.ratelimit import get_order_limiter
+
+    get_order_limiter().clear()
+
+    async def session_for(tid):
+        s = ChatSession(shop="x", tenant_id=tid)
+        db_session.add(s)
+        await db_session.flush()
+        return s
+
+    # Exhaust attempts for email in tenant A
+    for _ in range(8):
+        ctx_a = ToolContext(db=db_session, session=await session_for(a.id), tenant_id=a.id, shopify=FakeShopify())
+        await order_tool.run({"email": "spam@x.com", "order_number": "9999"}, ctx_a)
+
+    # Same email in tenant B is NOT locked (independent counter)
+    ctx_b = ToolContext(db=db_session, session=await session_for(b.id), tenant_id=b.id, shopify=FakeShopify())
+    out_b = await order_tool.run({"email": "spam@x.com", "order_number": "9999"}, ctx_b)
+    assert out_b["status"] == "not_found"  # not "locked"
+
+
 async def test_get_tenant_by_slug(db_session):
     db_session.add(Tenant(slug="toorx", brand_name="T"))
     await db_session.flush()

tests/test_prompts.py

@@ -10,7 +10,7 @@ def test_system_prompt_includes_rules_and_brand():
     assert "mismo idioma" in p
     assert "pt-PT" in p
     # anti-hallucination grounding rule
-    assert "no inventes" in p.lower()
+    assert "inventes" in p.lower()
     # flexible order verification (email + order number / postal code / name)
     assert "email" in p and "número de pedido" in p and "código postal" in p
     assert "NUNCA" in p  # no full address / payment