[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.
Python aifaissgpt-osslangchainllama-indexllmlocalstorageoffline-firstollamaprivacypythonragretrieval-augmented-generationvector-databasevector-searchvectors
feat: re-add web search with robust dual-source routing (#283) (#284)
Aakash Sureshf2b446f66df0
diff --git a/packages/leann-backend-diskann/pyproject.toml b/packages/leann-backend-diskann/pyproject.tomlindex 92330de..8745111 100644--- a/packages/leann-backend-diskann/pyproject.toml+++ b/packages/leann-backend-diskann/pyproject.toml@@ -17,4 +17,4 @@ editable.mode = "redirect"cmake.build-type = "Release"build.verbose = true# Let CMake find packages via Homebrew prefix-cmake.define = {CMAKE_PREFIX_PATH = {env = "CMAKE_PREFIX_PATH"}, OpenMP_ROOT = {env = "OpenMP_ROOT"}}+cmake.define = {CMAKE_PREFIX_PATH = {env = "CMAKE_PREFIX_PATH"}, OpenMP_ROOT = {env = "OpenMP_ROOT"}, USE_TCMALLOC = "OFF"}diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.pyindex faa18dc..4e7605c 100644--- a/packages/leann-core/src/leann/cli.py+++ b/packages/leann-core/src/leann/cli.py@@ -591,6 +591,18 @@ Examples:default=None,help="API key for cloud LLM providers (OpenAI, Anthropic)",)+ react_parser.add_argument(+ "--serper-api-key",+ type=str,+ default=None,+ help="Serper API key for web search (or set SERPER_API_KEY env var)",+ )+ react_parser.add_argument(+ "--jina-api-key",+ type=str,+ default=None,+ help="Jina API key for page content fetching (or set JINA_API_KEY env var)",+ )# List commandsubparsers.add_parser("list", help="List all indexes")@@ -2823,8 +2835,15 @@ Examples:index_path=index_path,llm_config=llm_config,max_iterations=args.max_iterations,+ serper_api_key=getattr(args, "serper_api_key", None),+ jina_api_key=getattr(args, "jina_api_key", None),)+ if agent.web_search_available:+ print("🌐 Web search enabled (Serper API key detected)")+ else:+ print("📚 Local search only (no Serper API key)")+print(f"\n🔍 Question: {query}\n")answer = agent.run(query, top_k=args.top_k)print(f"\n✅ Final Answer:\n{answer}\n")@@ -2832,8 +2851,10 @@ Examples:if agent.search_history:print(f"\n📊 Search History ({len(agent.search_history)} iterations):")for entry in agent.search_history:+ source_tag = f"[{entry.get('source', 'local')}]"print(- f" {entry['iteration']}. {entry['action']} ({entry['results_count']} results)"+ f" {entry['iteration']}. {source_tag} {entry['action']} "+ f"({entry['results_count']} results)")async def serve_api(self, args):diff --git a/packages/leann-core/src/leann/react_agent.py b/packages/leann-core/src/leann/react_agent.pyindex 1a63876..831486e 100644--- a/packages/leann-core/src/leann/react_agent.py+++ b/packages/leann-core/src/leann/react_agent.py@@ -3,7 +3,7 @@ Simple ReAct agent for multiturn retrieval with LEANN.This implements a basic ReAct (Reasoning + Acting) agent pattern:- Thought: LLM reasons about what to do next-- Action: Performs a search action+- Action: Performs a search action (local or web)- Observation: Gets results from search- Repeat until final answer@@ -13,23 +13,27 @@ Reference: Inspired by mini-swe-agent pattern, kept simple for multiturn retrievfrom __future__ import annotationsimport logging+import refrom typing import Anyfrom .api import LeannSearcher, SearchResultfrom .chat import LLMInterface, get_llm+from .web_search import WebSearcherlogger = logging.getLogger(__name__)class ReActAgent:"""- Simple ReAct agent for multiturn retrieval.+ ReAct agent for multiturn retrieval with local and web search.- The agent follows this pattern:- 1. Thought: LLM reasons about what information is needed- 2. Action: Performs a search query- 3. Observation: Gets search results- 4. Repeat until LLM decides it has enough information to answer+ Supports three tools:+ - leann_search: search the local knowledge base+ - web_search: search the public internet via Serper API (when configured)+ - visit_page: fetch full page content via Jina Reader (when configured)++ The agent dynamically adapts its prompt and behavior based on which+ tools are available (i.e., whether API keys are configured)."""def __init__(@@ -38,16 +42,9 @@ class ReActAgent:llm: LLMInterface | None = None,llm_config: dict[str, Any] | None = None,max_iterations: int = 5,+ serper_api_key: str | None = None,+ jina_api_key: str | None = None,):- """- Initialize the ReAct agent.-- Args:- searcher: LeannSearcher instance for performing searches- llm: LLM interface (if None, will create from llm_config)- llm_config: Configuration for creating LLM if llm is None- max_iterations: Maximum number of search iterations (default: 5)- """self.searcher = searcherif llm is None:self.llm = get_llm(llm_config)@@ -55,6 +52,8 @@ class ReActAgent:self.llm = llmself.max_iterations = max_iterationsself.search_history: list[dict[str, Any]] = []+ self.web_searcher = WebSearcher(api_key=serper_api_key, jina_api_key=jina_api_key)+ self.web_search_available = bool(self.web_searcher.api_key)def _format_search_results(self, results: list[SearchResult]) -> str:"""Format search results as a string for the LLM."""@@ -70,32 +69,60 @@ class ReActAgent:def _create_react_prompt(self, question: str, iteration: int, previous_observations: list[str]) -> str:- """Create the ReAct prompt for the LLM."""- prompt = f"""You are a helpful assistant that answers questions by searching through a knowledge base.--Question: {question}+ """Create the ReAct prompt, dynamically adapted to available tools."""+ if self.web_search_available:+ tools_block = (+ "You have access to these tools:\n"+ '1. leann_search("query"): Search the local private knowledge base (code, docs, history).\n'+ '2. web_search("query"): Search the public internet for up-to-date information.\n'+ '3. visit_page("url"): Read the full content of a specific URL.\n'+ "\nStrategies:\n"+ "- Use `leann_search` for internal project details, code implementation, or private history.\n"+ "- Use `web_search` for public documentation, latest news, or general concepts.\n"+ "- Use `visit_page` if you found a relevant link but need the full details.\n"+ "- You can combine both!"+ )+ action_examples = (+ 'Action: leann_search("your query")\n\nOR\n\n'+ "Thought: [your reasoning]\n"+ 'Action: web_search("your query")\n\nOR\n\n'+ "Thought: [your reasoning]\n"+ "Action: Final Answer: [your answer]"+ )+ else:+ tools_block = (+ "You have access to this tool:\n"+ '1. leann_search("query"): Search the local private knowledge base (code, docs, history).\n'+ "\nNote: Web search is not available (no API key configured). "+ "Answer using only the local knowledge base."+ )+ action_examples = (+ 'Action: leann_search("your query")\n\nOR\n\n'+ "Thought: [your reasoning]\n"+ "Action: Final Answer: [your answer]"+ )-You can search the knowledge base by using the action: search("query")+ prompt = (+ "You are a helpful assistant that answers questions by searching through "+ "a knowledge base"+ )+ if self.web_search_available:+ prompt += " AND the internet"+ prompt += f".\n\nQuestion: {question}\n\n{tools_block}\n\nPrevious observations:\n"-Previous observations:-"""if previous_observations:for i, obs in enumerate(previous_observations, 1):prompt += f"\nObservation {i}:\n{obs}\n"else:prompt += "None yet.\n"- prompt += f"""-Current iteration: {iteration}/{self.max_iterations}--Think step by step:-1. If you need more information, use search("your search query")-2. If you have enough information, provide your final answer--Format your response as:-Thought: [your reasoning]-Action: search("query") OR Final Answer: [your answer]-"""+ prompt += (+ f"\nCurrent iteration: {iteration}/{self.max_iterations}\n\n"+ "Think step by step.\n"+ "Format your response EXACTLY like this:\n\n"+ f"Thought: [your reasoning]\n{action_examples}\n\n"+ 'IMPORTANT: You MUST start a new line with "Action:" to trigger a tool.\n'+ )return prompt@@ -104,12 +131,13 @@ Action: search("query") OR Final Answer: [your answer]Parse LLM response to extract thought and action.Returns:- (thought, action) where action is either a search query string or None if final answer+ (thought, action) where action is a prefixed string like+ "leann_search:query", "web_search:query", "visit_page:url",+ or None if the agent wants to give a final answer."""thought = ""action = None- # Extract thoughtif "Thought:" in response:thought_part = response.split("Thought:")[1]if "Action:" in thought_part:@@ -119,57 +147,35 @@ Action: search("query") OR Final Answer: [your answer]else:thought = thought_part.strip()else:- # If no explicit Thought, use everything before Action/Final Answerif "Action:" in response or "Final Answer:" in response:thought = response.split("Action:")[0].split("Final Answer:")[0].strip()else:thought = response.strip()- # Extract actionif "Final Answer:" in response:- # Agent wants to provide final answeraction = Noneelif "Action:" in response:action_part = response.split("Action:")[1].strip()- # Try to extract search query- if 'search("' in action_part:- start = action_part.find('search("') + 7- end = action_part.find('")', start)- if end != -1:- action = action_part[start:end]- else:- # Try with single quote- end = action_part.find('")', start)- if end != -1:- action = action_part[start:end]- elif "search(" in action_part:- # Handle without quotes- start = action_part.find("search(") + 7- end = action_part.find(")", start)- if end != -1:- action = action_part[start:end].strip('"').strip("'")- elif "search(" in response.lower():- # Try to extract search query even if format is slightly different- import re+ match = re.search(+ r'(web_search|leann_search|visit_page|search)\(["\']([^"\']+)["\']\)',+ action_part,+ )+ if match:+ tool_name = match.group(1)+ if tool_name == "search":+ tool_name = "leann_search"+ action = f"{tool_name}:{match.group(2)}"+ elif "search(" in response.lower():match = re.search(r'search\(["\']([^"\']+)["\']\)', response, re.IGNORECASE)if match:- action = match.group(1)+ action = f"leann_search:{match.group(1)}"return thought, actiondef search(self, query: str, top_k: int = 5) -> list[SearchResult]:- """- Perform a search and return results.-- Args:- query: Search query string- top_k: Number of results to return-- Returns:- List of SearchResult objects- """- logger.info(f"🔍 Searching: {query}")+ """Perform a local search and return results."""+ logger.info(f"Searching: {query}")results = self.searcher.search(query, top_k=top_k)return results@@ -177,14 +183,11 @@ Action: search("query") OR Final Answer: [your answer]"""Run the ReAct agent to answer a question.- Args:- question: The question to answer- top_k: Number of search results per iteration-- Returns:- Final answer string+ The agent routes between local (leann_search) and web (web_search,+ visit_page) tools based on LLM reasoning. When web tools are+ unavailable, the agent gracefully falls back to local-only search."""- logger.info(f"🤖 Starting ReAct agent for question: {question}")+ logger.info(f"Starting ReAct agent for question: {question}")self.search_history = []previous_observations: list[str] = []all_context: list[str] = []@@ -192,52 +195,95 @@ Action: search("query") OR Final Answer: [your answer]for iteration in range(1, self.max_iterations + 1):logger.info(f"\n--- Iteration {iteration}/{self.max_iterations} ---")- # Create prompt for this iterationprompt = self._create_react_prompt(question, iteration, previous_observations)- # Get LLM response- logger.info("💭 Getting LLM reasoning...")+ logger.info("Getting LLM reasoning...")response = self.llm.ask(prompt)- # Parse responsethought, action = self._parse_llm_response(response)logger.info(f"Thought: {thought}")if action is None:- # LLM wants to provide final answerif "Final Answer:" in response:final_answer = response.split("Final Answer:")[1].strip()else:- # Extract answer from responsefinal_answer = response.strip()- # Remove any action markers if presentif "Action:" in final_answer:final_answer = final_answer.split("Action:")[0].strip()- logger.info(f"✅ Final answer: {final_answer}")+ logger.info(f"Final answer: {final_answer}")return final_answer- # Perform search action- logger.info(f'🔍 Action: search("{action}")')- results = self.search(action, top_k=top_k)+ logger.info(f"Action: {action}")++ results_count = 0++ if action.startswith("web_search:"):+ query_str = action.split(":", 1)[1]++ if not self.web_search_available:+ observation = (+ "Web search is not available (no SERPER_API_KEY configured). "+ "Use leann_search to search the local knowledge base instead."+ )+ results_count = 0+ else:+ web_results = self.web_searcher.search(query_str, top_k=top_k)++ is_error = len(web_results) == 1 and web_results[0].get("title") == "Error"+ if is_error:+ observation = (+ f"Web search failed: {web_results[0].get('snippet', 'Unknown error')}. "+ "Try leann_search for local results instead."+ )+ results_count = 0+ elif not web_results:+ observation = "No web results found."+ results_count = 0+ else:+ formatted = []+ for i, res in enumerate(web_results, 1):+ formatted.append(+ f"[Web Result {i}]\nTitle: {res['title']}\n"+ f"Link: {res['link']}\nSnippet: {res['snippet']}"+ )+ observation = "\n\n".join(formatted)+ results_count = len(web_results)++ elif action.startswith("visit_page:"):+ url = action.split(":", 1)[1]+ try:+ content = self.web_searcher.get_page_content(url)+ except Exception as e:+ content = f"Error fetching page: {e!s}"+ results_count = 1 if not content.startswith("Error") else 0+ observation = f"Content of {url}:\n{content[:15000]}"++ else:+ query_str = action.split(":", 1)[1] if ":" in action else action+ results = self.search(query_str, top_k=top_k)+ results_count = len(results)+ observation = self._format_search_results(results)- # Format observation- observation = self._format_search_results(results)previous_observations.append(observation)- all_context.append(f"Search: {action}\n{observation}")+ all_context.append(f"Action: {action}\n{observation}")++ if action.startswith("web_search:") or action.startswith("visit_page:"):+ source = "web"+ else:+ source = "local"- # Store in historyself.search_history.append({"iteration": iteration,"thought": thought,"action": action,- "results_count": len(results),+ "results_count": results_count,+ "source": source,})- # If no results, might want to stop early- if not results and iteration >= 2:+ if results_count == 0 and iteration >= 2:logger.warning("No results found, asking LLM for final answer...")final_prompt = f"""Based on the previous searches, provide your best answer to the question.@@ -251,7 +297,6 @@ Since no new results were found, provide your final answer based on what you knofinal_answer = self.llm.ask(final_prompt)return final_answer.strip()- # Max iterations reached, get final answerlogger.warning(f"Reached max iterations ({self.max_iterations}), getting final answer...")final_prompt = f"""Based on all the searches performed, provide your final answer to the question.@@ -270,19 +315,16 @@ def create_react_agent(index_path: str,llm_config: dict[str, Any] | None = None,max_iterations: int = 5,+ serper_api_key: str | None = None,+ jina_api_key: str | None = None,**searcher_kwargs,) -> ReActAgent:- """- Convenience function to create a ReActAgent.-- Args:- index_path: Path to LEANN index- llm_config: LLM configuration dict- max_iterations: Maximum search iterations- **searcher_kwargs: Additional kwargs for LeannSearcher-- Returns:- ReActAgent instance- """+ """Convenience function to create a ReActAgent."""searcher = LeannSearcher(index_path, **searcher_kwargs)- return ReActAgent(searcher=searcher, llm_config=llm_config, max_iterations=max_iterations)+ return ReActAgent(+ searcher=searcher,+ llm_config=llm_config,+ max_iterations=max_iterations,+ serper_api_key=serper_api_key,+ jina_api_key=jina_api_key,+ )diff --git a/packages/leann-core/src/leann/web_search.py b/packages/leann-core/src/leann/web_search.pynew file mode 100644index 0000000..72d4e70--- /dev/null+++ b/packages/leann-core/src/leann/web_search.py@@ -0,0 +1,65 @@+import json+import logging+import os+from typing import Any++import requests++logger = logging.getLogger(__name__)+++class WebSearcher:+ """Helper class for performing web searches via Serper API."""++ def __init__(self, api_key: str | None = None, jina_api_key: str | None = None):+ self.api_key = api_key or os.getenv("SERPER_API_KEY")+ self.jina_api_key = jina_api_key or os.getenv("JINA_API_KEY")+ if not self.api_key:+ logger.warning("No SERPER_API_KEY found. Web search will not be available.")++ def search(self, query: str, top_k: int = 5) -> list[dict[str, Any]]:+ if not self.api_key:+ return [{"title": "Error", "link": "", "snippet": "Missing SERPER_API_KEY env var"}]++ url = "https://google.serper.dev/search"+ payload = json.dumps({"q": query, "num": top_k})+ headers = {"X-API-KEY": self.api_key, "Content-Type": "application/json"}++ try:+ response = requests.request("POST", url, headers=headers, data=payload)+ response.raise_for_status()+ data = response.json()++ results = []++ if "organic" in data:+ for item in data["organic"][:top_k]:+ results.append(+ {+ "title": item.get("title", ""),+ "link": item.get("link", ""),+ "snippet": item.get("snippet", ""),+ }+ )++ return results+ except Exception as e:+ logger.error(f"Web search failed: {e}")+ return [{"title": "Error", "link": "", "snippet": f"Web search failed: {e!s}"}]++ def get_page_content(self, url: str) -> str:+ """Fetch page content using Jina AI Reader (https://jina.ai/reader)."""+ jina_url = f"https://r.jina.ai/{url}"++ headers = {"X-Return-Format": "markdown"}+ if self.jina_api_key:+ headers["Authorization"] = f"Bearer {self.jina_api_key}"++ try:+ logger.info(f"Fetching content from: {url}")+ response = requests.get(jina_url, headers=headers)+ response.raise_for_status()+ return response.text+ except Exception as e:+ logger.error(f"Failed to fetch content from {url}: {e}")+ return f"Error fetching content: {e!s}"diff --git a/tests/test_react_dual_source.py b/tests/test_react_dual_source.pynew file mode 100644index 0000000..4f2bfdc--- /dev/null+++ b/tests/test_react_dual_source.py@@ -0,0 +1,302 @@+"""+Tests for ReAct agent dual-source routing (issue #283).+Covers: prompt adaptation, web fallback, visit_page errors, routing, and pipeline.+"""++from unittest.mock import MagicMock, patch++from leann.api import SearchResult+from leann.react_agent import ReActAgent+from leann.web_search import WebSearcher+++def _make_searcher() -> MagicMock:+ """Create a lightweight mocked searcher for deterministic unit tests."""+ searcher = MagicMock()+ searcher.search.return_value = [+ SearchResult(+ id="1",+ score=0.91,+ text="LEANN achieves 97% storage reduction via graph pruning.",+ metadata={"source": "docs"},+ ),+ SearchResult(+ id="2",+ score=0.83,+ text="The search function uses HNSW for approximate nearest neighbors.",+ metadata={"source": "code"},+ ),+ ]+ return searcher+++# ── 1. Dual-source presence ──────────────────────────────────────────+++def test_prompt_includes_web_tools_when_key_present():+ """When SERPER_API_KEY is set, prompt should list all three tools."""+ searcher = _make_searcher()+ agent = ReActAgent(searcher=searcher, llm=MagicMock(), serper_api_key="test-key")+ prompt = agent._create_react_prompt("test question", 1, [])+ assert "web_search" in prompt+ assert "visit_page" in prompt+ assert "leann_search" in prompt+ assert agent.web_search_available is True+++def test_prompt_excludes_web_tools_when_no_key():+ """When no SERPER_API_KEY, prompt should only show leann_search."""+ searcher = _make_searcher()+ with patch.dict("os.environ", {}, clear=False):+ agent = ReActAgent(searcher=searcher, llm=MagicMock(), serper_api_key=None)+ prompt = agent._create_react_prompt("test question", 1, [])+ assert "leann_search" in prompt+ assert "web_search" not in prompt or "not available" in prompt+ assert agent.web_search_available is False+++# ── 2. Routing behavior ─────────────────────────────────────────────+++def test_local_only_routing():+ """Agent uses leann_search for local queries."""+ searcher = _make_searcher()+ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: This is about our codebase.\nAction: leann_search("LEANN storage reduction")',+ "Thought: I have the answer.\nAction: Final Answer: LEANN saves 97% storage.",+ ]+ agent = ReActAgent(searcher=searcher, llm=mock_llm, max_iterations=3)+ agent.run("How does LEANN reduce storage?", top_k=2)++ assert len(agent.search_history) >= 1+ assert agent.search_history[0]["source"] == "local"+ assert "leann_search" in agent.search_history[0]["action"]+++def test_web_only_routing():+ """Agent uses web_search for web queries (mocked)."""+ searcher = _make_searcher()++ with patch.object(WebSearcher, "search") as mock_web:+ mock_web.return_value = [+ {+ "title": "Python 3.13 News",+ "link": "https://python.org",+ "snippet": "New features in 3.13",+ }+ ]+ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: Need current web info.\nAction: web_search("Python 3.13 features")',+ "Thought: Got it.\nAction: Final Answer: Python 3.13 has new features.",+ ]+ agent = ReActAgent(+ searcher=searcher, llm=mock_llm, max_iterations=3, serper_api_key="test-key"+ )+ agent.run("What's new in Python 3.13?", top_k=2)++ assert len(agent.search_history) >= 1+ assert agent.search_history[0]["source"] == "web"+ mock_web.assert_called_once()+++def test_mixed_routing_local_then_web():+ """Agent uses leann_search first, then web_search."""+ searcher = _make_searcher()++ with patch.object(WebSearcher, "search") as mock_web:+ mock_web.return_value = [+ {+ "title": "Best Practices",+ "link": "https://example.com",+ "snippet": "Current best practices...",+ }+ ]+ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: First check our code.\nAction: leann_search("search implementation")',+ 'Thought: Now check best practices.\nAction: web_search("vector DB best practices")',+ "Thought: I can compare now.\nAction: Final Answer: Our search is good but could improve.",+ ]+ agent = ReActAgent(+ searcher=searcher, llm=mock_llm, max_iterations=5, serper_api_key="test-key"+ )+ agent.run("Compare our search with best practices", top_k=2)++ assert len(agent.search_history) >= 2+ assert agent.search_history[0]["source"] == "local"+ assert agent.search_history[1]["source"] == "web"+++# ── 3. Pipeline correctness ─────────────────────────────────────────+++def test_web_results_formatted_as_observations():+ """Web search results are properly formatted and passed to the next iteration."""+ searcher = _make_searcher()++ with patch.object(WebSearcher, "search") as mock_web:+ mock_web.return_value = [+ {"title": "Result A", "link": "https://a.com", "snippet": "Snippet A"},+ {"title": "Result B", "link": "https://b.com", "snippet": "Snippet B"},+ ]+ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: Search the web.\nAction: web_search("test query")',+ "Thought: Done.\nAction: Final Answer: Found it.",+ ]+ agent = ReActAgent(+ searcher=searcher, llm=mock_llm, max_iterations=3, serper_api_key="test-key"+ )+ agent.run("test", top_k=2)++ # The second LLM call should contain the formatted web results+ second_prompt = mock_llm.ask.call_args_list[1][0][0]+ assert "Result A" in second_prompt or "Snippet A" in second_prompt+++def test_visit_page_content_truncated():+ """visit_page content is truncated to 15k chars."""+ searcher = _make_searcher()++ with patch.object(WebSearcher, "get_page_content") as mock_fetch:+ mock_fetch.return_value = "x" * 20000+ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: Read this page.\nAction: visit_page("https://docs.python.org/3")',+ "Thought: Done.\nAction: Final Answer: Got the content.",+ ]+ agent = ReActAgent(+ searcher=searcher, llm=mock_llm, max_iterations=3, serper_api_key="test-key"+ )+ agent.run("read docs", top_k=2)++ second_prompt = mock_llm.ask.call_args_list[1][0][0]+ # Content should be truncated — observation contains at most 15000 chars of content+ assert "x" * 15000 in second_prompt+ assert "x" * 15001 not in second_prompt+++def test_leann_search_results_include_scores():+ """Local search results include scores and text snippets."""+ searcher = _make_searcher()+ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: Search locally.\nAction: leann_search("LEANN")',+ "Thought: Done.\nAction: Final Answer: Found results.",+ ]+ agent = ReActAgent(searcher=searcher, llm=mock_llm, max_iterations=3)+ agent.run("tell me about LEANN", top_k=2)++ second_prompt = mock_llm.ask.call_args_list[1][0][0]+ assert "Score:" in second_prompt+ assert "Result" in second_prompt+++# ── 4. Edge cases ────────────────────────────────────────────────────+++def test_web_search_no_api_key_graceful():+ """web_search without API key returns clear fallback message, not a crash."""+ searcher = _make_searcher()++ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: Try web.\nAction: web_search("Python 3.13")',+ 'Thought: Web failed, try local.\nAction: leann_search("search")',+ "Thought: Done.\nAction: Final Answer: Here's what I found locally.",+ ]+ with patch.dict("os.environ", {}, clear=False):+ agent = ReActAgent(searcher=searcher, llm=mock_llm, max_iterations=5, serper_api_key=None)+ answer = agent.run("test", top_k=2)++ assert agent.search_history[0]["results_count"] == 0+ assert agent.search_history[0]["source"] == "web"+ # Agent should not crash and should produce an answer+ assert answer is not None and len(answer) > 0+++def test_web_search_invalid_key_graceful():+ """Invalid Serper key returns error, agent continues."""+ searcher = _make_searcher()++ with patch.object(WebSearcher, "search") as mock_web:+ mock_web.return_value = [+ {"title": "Error", "link": "", "snippet": "Web Search failed:401 Unauthorized"}+ ]+ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: Try web.\nAction: web_search("test")',+ "Thought: Web failed.\nAction: Final Answer: Could not search web.",+ ]+ agent = ReActAgent(+ searcher=searcher, llm=mock_llm, max_iterations=3, serper_api_key="bad-key"+ )+ answer = agent.run("test", top_k=2)++ assert agent.search_history[0]["results_count"] == 0+ assert answer is not None+++def test_visit_page_404_graceful():+ """visit_page on a 404 URL returns error string, agent continues."""+ searcher = _make_searcher()++ with patch.object(WebSearcher, "get_page_content") as mock_fetch:+ mock_fetch.return_value = "Error fetching content: 404 Not Found"+ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: Read page.\nAction: visit_page("https://example.com/404")',+ "Thought: Page not found.\nAction: Final Answer: Page was not accessible.",+ ]+ agent = ReActAgent(+ searcher=searcher, llm=mock_llm, max_iterations=3, serper_api_key="test-key"+ )+ answer = agent.run("read page", top_k=2)++ assert agent.search_history[0]["results_count"] == 0+ assert "not accessible" in answer.lower() or len(answer) > 0+++def test_max_iterations_with_mixed_sources():+ """Agent hitting max iterations with mixed sources still produces an answer."""+ searcher = _make_searcher()++ with patch.object(WebSearcher, "search") as mock_web:+ mock_web.return_value = [+ {"title": "Web Result", "link": "https://example.com", "snippet": "Some web info"}+ ]+ mock_llm = MagicMock()+ # Never gives a Final Answer — forces max iterations+ mock_llm.ask.side_effect = [+ 'Thought: Search locally.\nAction: leann_search("storage")',+ 'Thought: Now web.\nAction: web_search("vector databases")',+ # Max iterations reached — the agent will ask for a final answer+ "Based on all searches, LEANN is a storage-efficient vector DB.",+ ]+ agent = ReActAgent(+ searcher=searcher, llm=mock_llm, max_iterations=2, serper_api_key="test-key"+ )+ answer = agent.run("Compare approaches", top_k=2)++ assert len(agent.search_history) == 2+ sources = {h["source"] for h in agent.search_history}+ assert "local" in sources+ assert "web" in sources+ assert answer is not None and len(answer) > 0+++def test_search_history_has_source_field():+ """search_history entries include 'source' field for easy inspection."""+ searcher = _make_searcher()+ mock_llm = MagicMock()+ mock_llm.ask.side_effect = [+ 'Thought: Local search.\nAction: leann_search("test")',+ "Thought: Done.\nAction: Final Answer: Done.",+ ]+ agent = ReActAgent(searcher=searcher, llm=mock_llm, max_iterations=3)+ agent.run("test", top_k=2)++ assert "source" in agent.search_history[0]+ assert agent.search_history[0]["source"] in ("local", "web")