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: Add simple ReAct agent for multiturn retrieval

aakash6281b2a97b08
diff --git a/packages/leann-core/src/leann/__init__.py b/packages/leann-core/src/leann/__init__.py
index 7ac156d..0181ec4 100644
--- a/packages/leann-core/src/leann/__init__.py
+++ b/packages/leann-core/src/leann/__init__.py
@@ -14,8 +14,16 @@ if platform.system() == "Darwin":
os.environ["TOKENIZERS_PARALLELISM"] = "false"
from .api import LeannBuilder, LeannChat, LeannSearcher
+from .react_agent import ReActAgent, create_react_agent
from .registry import BACKEND_REGISTRY, autodiscover_backends
autodiscover_backends()
-__all__ = ["BACKEND_REGISTRY", "LeannBuilder", "LeannChat", "LeannSearcher"]
+__all__ = [
+ "BACKEND_REGISTRY",
+ "LeannBuilder",
+ "LeannChat",
+ "LeannSearcher",
+ "ReActAgent",
+ "create_react_agent",
+]
diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.py
index 6a93748..f63b821 100644
--- a/packages/leann-core/src/leann/cli.py
+++ b/packages/leann-core/src/leann/cli.py
@@ -124,6 +124,7 @@ Examples:
leann build my-ppts --docs ./ --file-types .pptx,.pdf # Index only PowerPoint and PDF files
leann search my-docs "query" # Search in my-docs index
leann ask my-docs "question" # Ask my-docs index
+ leann react my-docs "complex question" # Use ReAct agent for multiturn retrieval
leann list # List all stored indexes
leann remove my-docs # Remove an index (local first, then global)
""",
@@ -396,6 +397,50 @@ Examples:
help="API key for cloud LLM providers (OpenAI, Anthropic)",
)
+ # React command (multiturn retrieval agent)
+ react_parser = subparsers.add_parser(
+ "react", help="Use ReAct agent for multiturn retrieval and reasoning"
+ )
+ react_parser.add_argument("index_name", help="Index name")
+ react_parser.add_argument("query", help="Question to research")
+ react_parser.add_argument(
+ "--llm",
+ type=str,
+ default="ollama",
+ choices=["simulated", "ollama", "hf", "openai", "anthropic"],
+ help="LLM provider (default: ollama)",
+ )
+ react_parser.add_argument(
+ "--model", type=str, default="qwen3:8b", help="Model name (default: qwen3:8b)"
+ )
+ react_parser.add_argument(
+ "--host",
+ type=str,
+ default=None,
+ help="Override Ollama-compatible host (defaults to LEANN_OLLAMA_HOST/OLLAMA_HOST)",
+ )
+ react_parser.add_argument(
+ "--top-k", type=int, default=5, help="Number of results per search (default: 5)"
+ )
+ react_parser.add_argument(
+ "--max-iterations",
+ type=int,
+ default=5,
+ help="Maximum number of search iterations (default: 5)",
+ )
+ react_parser.add_argument(
+ "--api-base",
+ type=str,
+ default=None,
+ help="Base URL for OpenAI-compatible APIs (e.g., http://localhost:10000/v1)",
+ )
+ react_parser.add_argument(
+ "--api-key",
+ type=str,
+ default=None,
+ help="API key for cloud LLM providers (OpenAI, Anthropic)",
+ )
+
# List command
subparsers.add_parser("list", help="List all indexes")
@@ -1715,6 +1760,77 @@ Examples:
_ask_once(query)
+ async def react_agent(self, args):
+ """Run ReAct agent for multiturn retrieval."""
+ index_name = args.index_name
+ query = args.query
+
+ # Find the index (similar to search_documents)
+ index_path = self.get_index_path(index_name)
+ if self.index_exists(index_name):
+ pass
+ else:
+ all_matches = self._find_all_matching_indexes(index_name)
+ if not all_matches:
+ print(
+ f"Index '{index_name}' not found. Use 'leann build {index_name} --docs <dir> [<dir2> ...]' to create it."
+ )
+ return
+ elif len(all_matches) == 1:
+ match = all_matches[0]
+ if match["kind"] == "cli":
+ index_path = str(match["index_dir"] / "documents.leann")
+ else:
+ meta_file = match["meta_file"]
+ file_base = match["file_base"]
+ index_path = str(meta_file.parent / f"{file_base}.leann")
+ else:
+ # Multiple matches - use first one for now
+ match = all_matches[0]
+ if match["kind"] == "cli":
+ index_path = str(match["index_dir"] / "documents.leann")
+ else:
+ meta_file = match["meta_file"]
+ file_base = match["file_base"]
+ index_path = str(meta_file.parent / f"{file_base}.leann")
+ print(f"Found {len(all_matches)} indexes named '{index_name}', using first match")
+
+ print(f"🤖 Starting ReAct agent with index '{index_name}'...")
+ print(f"Using {args.model} ({args.llm})")
+
+ llm_config = {"type": args.llm, "model": args.model}
+ if args.llm == "ollama":
+ llm_config["host"] = resolve_ollama_host(args.host)
+ elif args.llm == "openai":
+ llm_config["base_url"] = resolve_openai_base_url(args.api_base)
+ resolved_api_key = resolve_openai_api_key(args.api_key)
+ if resolved_api_key:
+ llm_config["api_key"] = resolved_api_key
+ elif args.llm == "anthropic":
+ if args.api_base:
+ llm_config["base_url"] = resolve_anthropic_base_url(args.api_base)
+ if args.api_key:
+ llm_config["api_key"] = args.api_key
+
+ from .react_agent import create_react_agent
+
+ agent = create_react_agent(
+ index_path=index_path,
+ llm_config=llm_config,
+ max_iterations=args.max_iterations,
+ )
+
+ print(f"\n🔍 Question: {query}\n")
+ answer = agent.run(query, top_k=args.top_k)
+ print(f"\n✅ Final Answer:\n{answer}\n")
+
+ if agent.search_history:
+ print(f"\n📊 Search History ({len(agent.search_history)} iterations):")
+ for entry in agent.search_history:
+ print(
+ f" {entry['iteration']}. {entry['action']} ({entry['results_count']} results)"
+ )
+
async def run(self, args=None):
parser = self.create_parser()
@@ -1742,6 +1858,9 @@ Examples:
elif args.command == "ask":
with suppress_cpp_output(suppress):
await self.ask_questions(args)
+ elif args.command == "react":
+ with suppress_cpp_output(suppress):
+ await self.react_agent(args)
else:
parser.print_help()
diff --git a/packages/leann-core/src/leann/react_agent.py b/packages/leann-core/src/leann/react_agent.py
new file mode 100644
index 0000000..1a63876
--- /dev/null
+++ b/packages/leann-core/src/leann/react_agent.py
@@ -0,0 +1,288 @@
+"""
+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
+- Observation: Gets results from search
+- Repeat until final answer
+
+Reference: Inspired by mini-swe-agent pattern, kept simple for multiturn retrieval.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .api import LeannSearcher, SearchResult
+from .chat import LLMInterface, get_llm
+
+logger = logging.getLogger(__name__)
+
+
+class ReActAgent:
+ """
+ Simple ReAct agent for multiturn retrieval.
+
+ 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
+ """
+
+ def __init__(
+ self,
+ searcher: LeannSearcher,
+ llm: LLMInterface | None = None,
+ llm_config: dict[str, Any] | None = None,
+ max_iterations: int = 5,
+ ):
+ """
+ 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)
+ else:
+ self.llm = llm
+ self.max_iterations = max_iterations
+ self.search_history: list[dict[str, Any]] = []
+
+ def _format_search_results(self, results: list[SearchResult]) -> str:
+ """Format search results as a string for the LLM."""
+ if not results:
+ return "No results found."
+ formatted = []
+ for i, result in enumerate(results, 1):
+ formatted.append(f"[Result {i}] (Score: {result.score:.3f})\n{result.text[:500]}...")
+ if result.metadata.get("source"):
+ formatted[-1] += f"\nSource: {result.metadata['source']}"
+ return "\n\n".join(formatted)
+
+ 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}
+
+You can search the knowledge base by using the action: search("query")
+
+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]
+"""
+
+ return prompt
+
+ def _parse_llm_response(self, response: str) -> tuple[str, str | None]:
+ """
+ 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 = None
+
+ # Extract thought
+ if "Thought:" in response:
+ thought_part = response.split("Thought:")[1]
+ if "Action:" in thought_part:
+ thought = thought_part.split("Action:")[0].strip()
+ elif "Final Answer:" in thought_part:
+ thought = thought_part.split("Final Answer:")[0].strip()
+ 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'search\(["\']([^"\']+)["\']\)', response, re.IGNORECASE)
+ if match:
+ action = 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}")
+ results = self.searcher.search(query, top_k=top_k)
+ return results
+
+ def run(self, question: str, top_k: int = 5) -> str:
+ """
+ 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
+ """
+ logger.info(f"🤖 Starting ReAct agent for question: {question}")
+ self.search_history = []
+ previous_observations: list[str] = []
+ all_context: list[str] = []
+
+ 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...")
+ 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}")
+ return final_answer
+
+ # Perform search action
+ logger.info(f'🔍 Action: search("{action}")')
+ results = self.search(action, top_k=top_k)
+
+ # Format observation
+ observation = self._format_search_results(results)
+ previous_observations.append(observation)
+ all_context.append(f"Search: {action}\n{observation}")
+
+ # Store in history
+ self.search_history.append(
+ {
+ "iteration": iteration,
+ "thought": thought,
+ "action": action,
+ "results_count": len(results),
+ }
+ )
+
+ # If no results, might want to stop early
+ if not results 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.
+
+Question: {question}
+
+Previous searches and results:
+{chr(10).join(all_context)}
+
+Since no new results were found, provide your final answer based on what you know.
+"""
+ 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.
+
+Question: {question}
+
+All search results:
+{chr(10).join(all_context)}
+
+Provide your final answer now.
+"""
+ final_answer = self.llm.ask(final_prompt)
+ return final_answer.strip()
+
+
+def create_react_agent(
+ index_path: str,
+ llm_config: dict[str, Any] | None = None,
+ max_iterations: int = 5,
+ **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
+ """
+ searcher = LeannSearcher(index_path, **searcher_kwargs)
+ return ReActAgent(searcher=searcher, llm_config=llm_config, max_iterations=max_iterations)