✨(websearch) add Brave llm/context snippets

Use llm/context endpoint with snippets, change tool name for web_search

Signed-off-by: camilleAND <camille.andre@modernisation.gouv.fr>

Author: camilleAND

src/backend/chat/agents/conversation.py

@@ -128,7 +128,8 @@ def get_web_search_tool_name(self) -> str | None:
         """
         for toolset in self.toolsets:
             for tool in toolset.tools.values():
-                if tool.name.startswith("web_search_"):
+                # Support both legacy names (web_search_*) and the new generic "web_search"
+                if tool.name == "web_search" or tool.name.startswith("web_search_"):
                     return tool.name
         return None
 

src/backend/chat/tests/clients/pydantic_ai/test_smart_web_search.py

@@ -23,7 +23,7 @@ def _llm_config_with_websearch(settings):
             is_active=True,
             icon=None,
             system_prompt="You are an amazing assistant.",
-            tools=["web_search_brave_with_document_backend"],
+            tools=["web_search"],
             provider=LLMProvider(
                 hrid="unused",
                 base_url="https://example.com",
@@ -68,7 +68,7 @@ def test_smart_search_enabled_tool_is_called(_llm_config_with_websearch):
     with service.conversation_agent.override(model=TestModel(), deps=service._context_deps):
         response = service.conversation_agent.run_sync("Search the web for something.")
 
-    assert "web_search_brave_with_document_backend" in response.output
+    assert "web_search" in response.output
 
 
 def test_force_websearch_overrides_smart_search_disabled(_llm_config_with_websearch):
@@ -92,4 +92,4 @@ def test_force_websearch_overrides_smart_search_disabled(_llm_config_with_websea
     )
     with service.conversation_agent.override(model=TestModel(), deps=service._context_deps):
         response = service.conversation_agent.run_sync("Search the web for something.")
-        assert "web_search_brave_with_document_backend" in response.output
+        assert "web_search" in response.output

src/backend/chat/tests/tools/test_web_search_brave.py

@@ -27,7 +27,8 @@
     web_search_brave_with_document_backend,
 )
 
-BRAVE_URL = "https://api.search.brave.com/res/v1/web/search"
+# Must match the URL used in _query_brave_api_async
+BRAVE_URL = "https://api.search.brave.com/res/v1/llm/context"
 
 
 @pytest.fixture(autouse=True)

src/backend/chat/tools/__init__.py

@@ -23,8 +23,17 @@ def get_pydantic_tools_by_name(name: str) -> Tool:
             prepare=only_if_web_search_enabled,
             max_retries=2,
         ),
+        # Backward-compatible alias (older settings may still reference this tool name).
         "web_search_brave_with_document_backend": Tool(
             web_search_brave_with_document_backend,
+            name="web_search_brave_with_document_backend",
+            takes_ctx=True,
+            prepare=only_if_web_search_enabled,
+            max_retries=2,
+        ),
+        "web_search": Tool(
+            web_search_brave_with_document_backend,
+            name="web_search",
             takes_ctx=True,
             prepare=only_if_web_search_enabled,
             max_retries=2,

src/backend/chat/tools/web_search_brave.py

@@ -101,6 +101,18 @@ async def _fetch_and_extract_async(url: str) -> str:
         raise DocumentFetchError(f"Failed to extract content from {url}: {e}") from e
 
 
+def _get_snippets_from_result(result: dict) -> List[str]:
+    """Return merged snippets/extra_snippets as a list, guarding against None."""
+    snippets = result.get("snippets") or []
+    extra_snippets = result.get("extra_snippets") or []
+    # Both are expected to be lists of strings; fall back to one or the other if needed.
+    if snippets and not extra_snippets:
+        return snippets
+    if extra_snippets and not snippets:
+        return extra_snippets
+    return snippets or extra_snippets
+
+
 async def _extract_and_summarize_snippets_async(query: str, url: str) -> List[str]:
     """Fetch, extract and summarize text content from the URL.
 
@@ -144,7 +156,11 @@ async def _fetch_and_store_async(url: str, document_store, **kwargs) -> None:
 
 async def _query_brave_api_async(query: str) -> List[dict]:
     """Query the Brave Search API and return the raw results."""
-    url = "https://api.search.brave.com/res/v1/web/search"
+    # NOTE:
+    # - Standard web search endpoint: https://api.search.brave.com/res/v1/web/search
+    # - LLM context endpoint:       https://api.search.brave.com/res/v1/llm/context
+    #   The latter returns results under `grounding.generic` instead of `web.results`.
+    url = "https://api.search.brave.com/res/v1/llm/context"
     headers = {
         "Accept": "application/json",
         "X-Subscription-Token": settings.BRAVE_API_KEY,
@@ -158,6 +174,10 @@ async def _query_brave_api_async(query: str) -> List[dict]:
         "spellcheck": settings.BRAVE_SEARCH_SPELLCHECK,
         "result_filter": "web,faq,query",
         "extra_snippets": settings.BRAVE_SEARCH_EXTRA_SNIPPETS,
+        "maximum_number_of_urls": settings.BRAVE_MAX_RESULTS,
+        "maximum_number_of_tokens": settings.BRAVE_MAX_TOKENS,
+        "maximum_number_of_snippets": settings.BRAVE_MAX_SNIPPETS,
+        "maximum_number_of_snippets_per_url": settings.BRAVE_MAX_SNIPPETS_PER_URL,
     }
     params = {k: v for k, v in data.items() if v is not None}
 
@@ -167,6 +187,29 @@ async def _query_brave_api_async(query: str) -> List[dict]:
             response.raise_for_status()
             json_response = response.json()
 
+            # LLM context API: results are under `grounding.generic`
+            # See: https://api-dashboard.search.brave.com/documentation/services/llm-context
+            if "grounding" in json_response:
+                generic_results = json_response.get("grounding", {}).get("generic", []) or []
+                normalized_results: List[dict] = []
+                for item in generic_results:
+                    item_url = item.get("url")
+                    if not item_url:
+                        continue
+
+                    normalized_results.append(
+                        {
+                            "url": item_url,
+                            # Fallback to URL if no title is provided
+                            "title": item.get("title") or item_url,
+                            # `snippets` is already a list
+                            "snippets": item.get("snippets") or [],
+                        }
+                    )
+
+                return normalized_results
+
+            # Fallback for classic web search JSON shape, if we ever switch back
             # https://api-dashboard.search.brave.com/app/documentation/web-search/responses#Result
             return json_response.get("web", {}).get("results", [])
 
@@ -211,20 +254,22 @@ async def _query_brave_api_async(query: str) -> List[dict]:
 
 def format_tool_return(raw_search_results: List[dict]) -> ToolReturn:
     """Format the raw search results into a ToolReturn object."""
+    logger.debug("Raw search results: %s", raw_search_results)
+    logger.debug("Unduplicated sources: %s", {result["url"] for result in raw_search_results})
     return ToolReturn(
         # Format return value "mistral-like": https://docs.mistral.ai/capabilities/citations/
         return_value={
             str(idx): {
                 "url": result["url"],
                 "title": result["title"],
-                "snippets": result.get("extra_snippets", []),
+                "snippets": _get_snippets_from_result(result),
             }
             for idx, result in enumerate(raw_search_results)
-            if result.get("extra_snippets", [])
+            if _get_snippets_from_result(result)
         },
         metadata={
             "sources": {
-                result["url"] for result in raw_search_results if result.get("extra_snippets", [])
+                result["url"] for result in raw_search_results if _get_snippets_from_result(result)
             }
         },
     )
@@ -244,9 +289,12 @@ async def web_search_brave(_ctx: RunContext, query: str) -> ToolReturn:
 
         await sync_to_async(reset_caches)()  # Clear trafilatura caches to avoid memory bloat/leaks
 
-        # Parallelize fetch/extract for results that don't include extra_snippets
+        # Parallelize fetch/extract only for results that don't already include any snippets
+        # (neither Brave `snippets` nor `extra_snippets`).
         to_process = [
-            (idx, r) for idx, r in enumerate(raw_search_results) if not r.get("extra_snippets")
+            (idx, r)
+            for idx, r in enumerate(raw_search_results)
+            if not r.get("extra_snippets") and not r.get("snippets")
         ]
 
         if to_process:
@@ -292,7 +340,7 @@ async def web_search_brave_with_document_backend(ctx: RunContext, query: str) ->
         ctx (RunContext): The run context containing the conversation.
         query (str): The query to search for.
     """
-    logger.info("Starting web search with RAG backend for query: %s", query)
+    logger.debug("Starting web search with RAG backend for query: %s", query)
     try:
         raw_search_results = await _query_brave_api_async(query)
 
@@ -328,7 +376,7 @@ async def web_search_brave_with_document_backend(ctx: RunContext, query: str) ->
                     session=ctx.deps.session,
                     user_sub=ctx.deps.user.sub,
                 )
-                logger.info("RAG search returned:  %s", rag_results)
+                logger.debug("RAG search returned:  %s", rag_results)
 
                 ctx.usage += RunUsage(
                     input_tokens=rag_results.usage.prompt_tokens,

src/backend/conversations/brave_settings.py

@@ -74,3 +74,20 @@ class BraveSettings:
         environ_name="BRAVE_SEARCH_EXTRA_SNIPPETS",
         environ_prefix=None,
     )
+
+    # LLM context endpoint limits
+    BRAVE_MAX_TOKENS = values.IntegerValue(
+        default=8192,
+        environ_name="BRAVE_MAX_TOKENS",
+        environ_prefix=None,
+    )
+    BRAVE_MAX_SNIPPETS = values.IntegerValue(
+        default=50,
+        environ_name="BRAVE_MAX_SNIPPETS",
+        environ_prefix=None,
+    )
+    BRAVE_MAX_SNIPPETS_PER_URL = values.IntegerValue(
+        default=10,
+        environ_name="BRAVE_MAX_SNIPPETS_PER_URL",
+        environ_prefix=None,
+    )