Skip to content

armgit / LEANN

Public Imported from GitHub
0

[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.

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.toml
index 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.py
index 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 command
subparsers.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.py
index 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 retriev
from __future__ import annotations
import logging
+import re
from typing import Any
from .api import LeannSearcher, SearchResult
from .chat import LLMInterface, get_llm
+from .web_search import WebSearcher
logger = 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 = searcher
if llm is None:
self.llm = get_llm(llm_config)
@@ -55,6 +52,8 @@ class ReActAgent:
self.llm = llm
self.max_iterations = max_iterations
self.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 thought
if "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 Answer
if "Action:" in response or "Final Answer:" in response:
thought = response.split("Action:")[0].split("Final Answer:")[0].strip()
else:
thought = response.strip()
- # Extract action
if "Final Answer:" in response:
- # Agent wants to provide final answer
action = None
elif "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, action
def 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 iteration
prompt = 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 response
thought, action = self._parse_llm_response(response)
logger.info(f"Thought: {thought}")
if action is None:
- # LLM wants to provide final answer
if "Final Answer:" in response:
final_answer = response.split("Final Answer:")[1].strip()
else:
- # Extract answer from response
final_answer = response.strip()
- # Remove any action markers if present
if "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 history
self.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 kno
final_answer = self.llm.ask(final_prompt)
return final_answer.strip()
- # Max iterations reached, get final answer
logger.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.py
new file mode 100644
index 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.py
new file mode 100644
index 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")