deep-searcher

Implements three distinct RAG strategies (NaiveRAG, ChainOfRAG, DeepSearch) that can be selected via configuration or automatically routed based on query complexity. NaiveRAG performs single-pass retrieval-generation for simple queries; ChainOfRAG decomposes complex queries into sub-questions with iterative multi-hop reasoning and early stopping; DeepSearch executes parallel searches with LLM-based reranking and reflection loops for comprehensive research tasks. The agent selection is configuration-driven through the agent provider setting, enabling runtime strategy swapping without code changes.

Provides pluggable file loader and web crawler implementations for ingesting diverse data sources into the vector database. Supports local file formats (PDF, text, markdown) and web content crawling through configurable loader and crawler provider classes. The offline_loading process orchestrates chunking, embedding generation via the configured embedding provider, and vector storage into Milvus or alternative vector databases. Data ingestion is decoupled from querying, enabling batch preprocessing of large document collections.

Implements the offline_loading process that orchestrates document ingestion, chunking, embedding generation, and vector storage. The pipeline loads documents using configured file loaders and web crawlers, chunks documents into fixed-size or semantic chunks, generates embeddings for each chunk using the configured embedding provider, and inserts embeddings into the vector database with metadata. This process is decoupled from query processing, enabling batch preprocessing of large document collections without blocking user queries. The pipeline is designed for one-time or periodic execution rather than real-time ingestion.

Implements the online_query process that retrieves relevant context from the vector database and generates answers using the configured LLM. The process encodes the user query as a vector embedding, searches the vector database for similar documents, constructs a prompt with retrieved context and the original query, and calls the LLM to generate an answer. The LLM has access to retrieved context, enabling it to provide grounded answers with citations. This process is optimized for low-latency query serving and can be executed repeatedly without modifying indexed data.

Implements streaming response generation that yields LLM output tokens one at a time rather than waiting for complete response generation. This capability is supported by LLM providers that implement streaming APIs (OpenAI, Anthropic, DeepSeek, etc.). Streaming enables real-time feedback to users, reduces perceived latency, and allows early termination if the user stops reading. The streaming interface is available through both the FastAPI web service (Server-Sent Events) and Python API (generator functions).

Provides Docker containerization and Kubernetes deployment patterns for production deployment of DeepSearcher. The system can be containerized with all dependencies (Python, LLM clients, embedding libraries, vector database clients) and deployed as microservices. Kubernetes manifests enable horizontal scaling of query processing, load balancing across instances, and automatic failover. The FastAPI web service is designed for containerized deployment with health checks and graceful shutdown.

Provides a unified LLM provider interface that abstracts over 17+ language model providers including OpenAI, DeepSeek, Anthropic, Grok, Qwen, and local models. Each provider is implemented as a pluggable class (e.g., OpenAI, DeepSeek, AnthropicLLM, SiliconFlow, TogetherAI) with standardized method signatures for completion and streaming. Provider selection is configuration-driven via the llm_provider setting, enabling runtime swapping between cloud and local models without code changes. Supports both standard LLMs and specialized reasoning models (DeepSeek-R1, Grok-3).

Provides a unified embedding provider interface supporting 15+ embedding models from cloud providers (OpenAI, Cohere, Hugging Face) and local models (Sentence Transformers, Ollama). Each provider is implemented as a pluggable class with standardized embed() methods that return vector embeddings. Provider selection is configuration-driven via the embedding_provider setting, enabling runtime swapping between cloud and local embeddings. Embeddings are generated during offline_loading and used for semantic search during query processing.

Provides a pluggable vector database provider interface supporting Milvus (open-source), Zilliz Cloud (managed), and alternative vector databases. The base VectorDB class defines standardized methods for insert, search, and delete operations. Provider implementations handle connection management, index creation, and similarity search. Vector database selection is configuration-driven via the vector_db_provider setting, enabling runtime swapping between on-premises Milvus and managed Zilliz Cloud without code changes. Supports semantic search queries during online_query processing.

Implements a centralized Configuration class and config.yaml file that manages provider selection across LLMs, embeddings, vector databases, file loaders, and web crawlers. The init_config() and set_provider_config() methods enable runtime provider changes without code modifications. Configuration is loaded at startup and can be updated dynamically. This design pattern decouples provider implementations from application logic, enabling teams to swap entire technology stacks (e.g., OpenAI→DeepSeek, Milvus→Zilliz Cloud) through configuration changes alone.

Provides three distinct usage interfaces: (1) CLI via the deepsearcher command for command-line workflows, (2) FastAPI web service for HTTP-based access with REST endpoints, and (3) Python library API for programmatic integration. All interfaces share the same underlying core engines (offline_loading, online_query) and RAG agents, enabling consistent behavior across access methods. This design enables diverse deployment patterns: CLI for batch processing, FastAPI for web applications, and Python API for integration into larger systems.

Implements the ChainOfRAG agent that decomposes complex queries into sub-questions, iteratively retrieves relevant context for each sub-question, and synthesizes answers with early stopping logic. The agent uses the configured LLM to generate sub-questions, performs semantic search for each sub-question in the vector database, and combines results into a comprehensive answer. Early stopping logic terminates iteration when sufficient information is retrieved or a maximum iteration count is reached. This strategy is optimized for multi-hop reasoning tasks that require breaking down complex information needs.

Implements the DeepSearch agent that executes parallel semantic searches, applies LLM-based reranking to retrieved documents, and performs reflection loops to evaluate answer quality and iterate if needed. The agent retrieves multiple candidate documents in parallel, uses the configured LLM to score and rerank results based on relevance to the query, and generates reflection prompts to assess answer completeness. If reflection indicates insufficient information, the agent performs additional searches with refined queries. This strategy is optimized for comprehensive research tasks requiring high-quality answers.

Implements semantic search by encoding queries and documents as vector embeddings using the configured embedding provider, storing embeddings in the vector database, and retrieving documents based on cosine similarity or other distance metrics. During offline_loading, document chunks are embedded and indexed. During online_query, the user query is embedded and used to search the vector database, returning top-k most similar documents. This approach enables semantic understanding beyond keyword matching, allowing retrieval of documents with similar meaning even if they use different terminology.