# zilliztech/deep-searcher architecture

> Architecture diagram of the GitHub repository zilliztech/deep-searcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zilliztech/deep-searcher
- Repository: https://github.com/zilliztech/deep-searcher
- Video tour (about a minute): https://gitdiagram.com/zilliztech/deep-searcher/video

## Overview

##### Main Components
- Configuration & Initialization: Represent the Configuration module (configuration.py, config.yaml) which sets up provider configurations for LLMs, Embeddings, vector databases, file loaders, and web crawlers.
- Core Processing Modules:
– Agent: Components under deepsearcher/agent (base, chain_of_rag, deep_search, etc.) that coordinate reasoning and searching.
– Embedding: Modules in deepsearcher/embedding that interface with various embedding models (OpenAIEmbedding, MilvusEmbedding, etc.).
– LLM: Components in deepsearcher/llm wrapping various language models (OpenAI, DeepSeek, Anthropic, etc.).
– Loader: The file loader and web crawler modules (in deepsearcher/loader) for ingesting local and online data.
– Vector Database: The deepsearcher/vector_db module that encapsulates interactions with Milvus, Oracle, Qdrant, etc.
- CLI & API Interface:
– CLI: The command-line interface (deepsearcher/cli.py) to load data and perform queries.
– FastAPI Service: main.py initiates a web service (accessible via localhost:8000/docs) providing API endpoints for query processing.
- Evaluation & Examples:
– Evaluation directory that supports performance assessment and result plotting.
– Examples directory that contains scripts demonstrating typical usage of the system.

##### Relationships and Interactions
- Configuration → [LLM, Embedding, VectorDB, File Loader, Web Crawler]: The configuration sets provider-specific parameters and is used across various modules.
- Data Ingestion Flow: The file loaders (file_loader) and web crawlers (web_crawler) import documents from local sources or online, which then get processed by the splitter and eventually indexed into the vector database.
- Query Handling Pipeline: Incoming queries (via CLI or FastAPI) are routed to the online_query module, where the agent module orchestrates calls to an LLM and an embedding service. The retrieved embeddings then interact with the VectorDB to search for relevant content.
- Output/Results: The agent compiles the results (e.g., reports or Q&A responses) that are returned to the end-user.

##### Architectural Patterns & Design Principles
- Modular Design: Separate modules for embeddings, LLMs, loaders, and vector databases, which promotes plug-and-play extensibility.
- Provider Abstraction: Each category (LLM, embedding, file loader, etc.) is abstracted behind a configuration interface, making it extensible for multiple external providers.
- API and CLI Exposure: Dual interface mode (CLI and web service) allows for flexibility in integration.
- Support for both offline and online modes for data ingestion and query processing.

##### Relevant Technologies and Frameworks
- Python (3.10+)
- FastAPI for the web service (main.py)
- CLI scripting for command-line operations.
- Various third-party APIs and libraries for LLMs (OpenAI, DeepSeek, Anthropic, etc.), embedding models, and vector databases (Milvus, Qdrant, Oracle).

##### Final Checklist for the Principal Software Engineer
- Every module (Configuration, Agents, Embedding, LLM, Loader, VectorDB, CLI/API) is clearly labeled.
– Configuration to each service (LLM, Embedding, etc.)
– Data flow from ingestion (file loaders/web crawlers) to vector database.
– Query requests from CLI/API to the agent.
- Critical control flows like initialization (via main.py FastAPI service) and query handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Initialization Layer
    subgraph "Configuration & Initialization"
        CF["Config File"]:::config
        CM["Configuration Module"]:::config
    end

    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        FL["File Loader"]:::ingest
        WC["Web Crawler"]:::ingest
        SP["Data Splitter"]:::ingest
    end

    %% Processing Layer
    subgraph "Processing Layer"
        AG["Agent Module"]:::process
        EM["Embedding Module"]:::process
        LM["LLM Module"]:::process
    end

    %% Storage Layer
    subgraph "Storage Layer"
        VD["Vector DB Module"]:::storage
    end

    %% Interface Layer
    subgraph "Interface Layer"
        CLI["CLI Interface"]:::interface
        API["FastAPI Service"]:::interface
    end

    %% Evaluation & Examples
    subgraph "Evaluation & Examples"
        EV["Evaluation"]:::extra
        EX["Examples"]:::extra
    end

    %% Configuration influences all modules
    CF -->|"configures"| AG
    CF -->|"configures"| EM
    CF -->|"configures"| LM
    CF -->|"configures"| FL
    CF -->|"configures"| WC
    CF -->|"configures"| SP
    CF -->|"configures"| VD

    CM -->|"sets parameters"| AG
    CM -->|"sets parameters"| EM
    CM -->|"sets parameters"| LM
    CM -->|"sets parameters"| FL
    CM -->|"sets parameters"| WC
    CM -->|"sets parameters"| SP
    CM -->|"sets parameters"| VD

    %% Data Ingestion Flow
    FL -->|"loads data"| SP
    WC -->|"crawls data"| SP
    SP -->|"indexes documents"| VD

    %% Query Handling Pipeline
    CLI -->|"submits query"| AG
    API -->|"submits query"| AG
    AG -->|"invokes"| LM
    AG -->|"invokes"| EM
    EM -->|"retrieves embeddings"| VD
    VD -->|"returns matches"| AG
    AG -->|"responds to"| CLI
    AG -->|"responds to"| API

    %% Evaluation connection (optional flow)
    AG -->|"evaluation data"| EV
    EV -->|"feedback"| AG
    EX ---|"demonstrates usage"| AG

    %% Click Events for Component Mapping
    click CF "https://github.com/zilliztech/deep-searcher/blob/master/config.yaml"
    click CM "https://github.com/zilliztech/deep-searcher/blob/master/deepsearcher/configuration.py"
    click AG "https://github.com/zilliztech/deep-searcher/tree/master/deepsearcher/agent"
    click EM "https://github.com/zilliztech/deep-searcher/tree/master/deepsearcher/embedding"
    click LM "https://github.com/zilliztech/deep-searcher/tree/master/deepsearcher/llm"
    click FL "https://github.com/zilliztech/deep-searcher/tree/master/deepsearcher/loader/file_loader"
    click WC "https://github.com/zilliztech/deep-searcher/tree/master/deepsearcher/loader/web_crawler"
    click SP "https://github.com/zilliztech/deep-searcher/blob/master/deepsearcher/loader/splitter.py"
    click VD "https://github.com/zilliztech/deep-searcher/tree/master/deepsearcher/vector_db"
    click CLI "https://github.com/zilliztech/deep-searcher/blob/master/deepsearcher/cli.py"
    click API "https://github.com/zilliztech/deep-searcher/blob/master/main.py"
    click EV "https://github.com/zilliztech/deep-searcher/tree/master/evaluation"
    click EX "https://github.com/zilliztech/deep-searcher/tree/master/examples"

    %% Styles
    classDef config fill:#a2d2ff,stroke:#036,stroke-width:2px;
    classDef ingest fill:#d0f0c0,stroke:#0a3,stroke-width:2px;
    classDef process fill:#ffdd94,stroke:#c60,stroke-width:2px;
    classDef storage fill:#fff5ba,stroke:#aa7,stroke-width:2px;
    classDef interface fill:#f9c0c0,stroke:#d00,stroke-width:2px;
    classDef extra fill:#e0ccff,stroke:#800080,stroke-width:2px;
```
