trust: proactive real-source citation in bot replies

app/tools/knowledge_tool.py

@@ -98,8 +98,15 @@ async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
     out: dict[str, Any] = {"context": "\n\n".join(blocks), "sources": sources}
     if links:
         out["links"] = links
+        # Proactive citation builds real trust (the customer can verify a policy
+        # claim themselves) instead of just asking the shopper to take the bot's
+        # word for it -- especially for concrete/checkable facts (returns,
+        # shipping windows, warranty, prices). Not every trivial reply needs one.
         out["hint"] = (
-            "Si el cliente pide un enlace, usa EXACTAMENTE una de estas URLs (no "
-            "inventes ni modifiques rutas)."
+            "Cuando cites una política o un dato concreto y verificable "
+            "(devoluciones, envíos, garantía, precios, plazos), añade el enlace "
+            "real al final en formato [nombre](url) para que el cliente pueda "
+            "comprobarlo — genera confianza. Usa EXACTAMENTE una de estas URLs, "
+            "nunca inventes ni modifiques rutas."
         )
     return out

tests/tools/test_tools.py

@@ -133,6 +133,41 @@ async def test_dispatch_knowledge_returns_context(db_session, monkeypatch):
     assert out["sources"] == ["FAQ"]
 
 
+async def test_knowledge_tool_nudges_proactive_citation_with_real_link(db_session, monkeypatch):
+    """Trust: when the KB match has a real, verified URL, the model is told to
+    proactively CITE it for concrete/checkable claims (returns, shipping, price)
+    -- not just when the shopper explicitly asks for a link. The widget already
+    renders [name](url) as a real clickable link."""
+    from app import embeddings as emb
+
+    async def fake_query(q):
+        return [1.0, 0.0]
+
+    async def fake_texts(texts, *, kind="passage"):
+        return [[1.0, 0.0] for _ in texts]
+
+    monkeypatch.setattr(emb, "embed_query", fake_query)
+    monkeypatch.setattr(emb, "embed_texts", fake_texts)
+
+    src = KnowledgeSource(kind="url", name="Política de envíos", location="https://tienda.example/envios")
+    db_session.add(src)
+    await db_session.flush()
+    db_session.add(
+        KnowledgeChunk(
+            source_id=src.id, ordinal=0, text="Envíos gratis desde 199€", embedding=[1.0, 0.0],
+            meta={"source_name": "Política de envíos"},
+        )
+    )
+    await db_session.flush()
+
+    ctx = ToolContext(db=db_session, session=await _session(db_session))
+    out = await registry.dispatch("search_knowledge", {"query": "envíos"}, ctx)
+    assert out["links"] == [{"name": "Política de envíos", "url": "https://tienda.example/envios"}]
+    assert "[nombre](url)" in out["hint"]          # tells the model the exact citable format
+    assert "verificable" in out["hint"]            # nudges WHEN to cite (concrete/checkable claims)
+    assert "EXACTAMENTE una de estas URLs" in out["hint"]  # still forbids inventing routes
+
+
 async def test_dispatch_products_surfaces_cards_and_add_url(db_session):
     payload = {
         "products": {