# jerry-ai-dev/modular-rag-mcp-server architecture

> Architecture diagram of the GitHub repository jerry-ai-dev/modular-rag-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jerry-ai-dev/modular-rag-mcp-server
- Repository: https://github.com/jerry-ai-dev/modular-rag-mcp-server

## Overview

1. **What this repository is**
   This is a Python-based modular RAG system exposed as an **MCP server**. The runtime product is not just retrieval: it includes ingestion, hybrid search, reranking, response assembly with citations/multimodal support, observability, evaluation, and a Streamlit dashboard.

2. **Top-level runtime entrypoints**
   The main operational entrypoints are `main.py` and the scripts under `scripts/`: `ingest.py`, `query.py`, `evaluate.py`, and `start_dashboard.py`. These are thin orchestration layers that connect configuration, pipeline components, and the service surfaces.

3. **Core architectural boundary: `src/libs` vs `src/core` vs `src/ingestion`**
   `src/libs` contains the pluggable provider/adaptor implementations and factories: LLMs, embeddings, rerankers, splitters, vector store, loader, and evaluator backends. `src/ingestion` and `src/core` contain the application workflows built on top of those adapters. This separation is the key design boundary: backends can be swapped without changing the main pipelines.

4. **Ingestion pipeline: document to indexed knowledge**
   The ingestion flow is centered in `src/ingestion/pipeline.py` and `document_manager.py`. Documents are loaded via loader implementations such as `pdf_loader.py`, checked by `file_integrity.py`, chunked by `document_chunker.py`, optionally refined/enriched/captioned through transforms, embedded in batches, and finally written to storage. The storage side fans out into a vector upsert path, a BM25 indexer, and image storage for multimodal assets.

5. **Multimodal handling**
   The repository treats images as first-class knowledge content. `image_captioner.py` uses a vision LLM backend to generate text descriptions, so images can be folded back into the text-centric RAG pipeline. This lets the retrieval layer search across documents with embedded visual context without needing a separate image QA subsystem.

6. **Retrieval architecture: hybrid search**
   Query-time retrieval is implemented in `src/core/query_engine`. The flow is: query processing → dense retrieval → sparse retrieval → fusion → optional reranking. Dense search uses embeddings and the vector store; sparse search uses BM25; `fusion.py` combines them with reciprocal rank fusion; rerankers then refine the top candidates. This is the central relevance architecture of the system.

7. **Response assembly**
   Retrieved chunks are turned into final answers in `src/core/response`. `response_builder.py` coordinates answer construction, `citation_generator.py` attaches source references, and `multimodal_assembler.py` can merge textual and image-derived context. This is where the system turns retrieval results into an assistant-facing response rather than just returning documents.

8. **MCP server layer**
   `src/mcp_server` wraps the RAG capability as standardized MCP tools. The tools exposed in `tools/` include `query_knowledge_hub`, `list_collections`, and `get_document_summary`. `protocol_handler.py` and `server.py` handle the protocol boundary, allowing external MCP clients such as AI assistants to call into the knowledge system.

9. **Observability and traces**
   The system is designed to be white-box observable. `src/core/trace` defines trace context and collection for ingestion/query lifecycles, and the dashboard services in `src/observability/dashboard/services` read those traces and associated data. The dashboard pages provide views for overview, data browsing, ingestion management, ingestion traces, query traces, and evaluation results.

10. **Evaluation and regression testing**
   Evaluation is a first-class subsystem under `src/observability/evaluation`. `eval_runner.py`, `composite_evaluator.py`, `ragas_evaluator.py`, and `custom_evaluator.py` support both framework-based and custom scoring. The repo also includes a golden test set in `tests/fixtures/` and end-to-end/integration tests to validate ingestion, retrieval recall, MCP behavior, and dashboard smoke tests.

11. **Configuration and prompt assets**
   `src/core/settings.py` and `config/settings.yaml` centralize runtime configuration. `config/prompts/` stores prompt templates for chunk refinement, metadata enrichment, image captioning, and reranking. This keeps prompt behavior and backend selection outside business logic, reinforcing the pluggable design.

12. **External services and backend options**
   The repo is built to work with multiple provider families: OpenAI, Azure OpenAI, Ollama, and DeepSeek for LLM/vision tasks; ChromaDB as the vector store; BM25 as sparse retrieval. The factories in `src/libs/*_factory.py` are the switch points that let the same architecture run against different local or cloud backends.

13. **Testing and validation structure**
   The `tests/` tree mirrors the runtime boundaries: unit tests validate isolated adapters and core logic, integration tests cover real provider and storage interactions, and e2e tests exercise the full ingestion/query/dashboard/MCP flows. This mirrors the architecture well and is important for any diagram because it shows which boundaries are meant to be stable integration points.

14. **Developer tooling is separate from runtime**
   The `.claude/` and `.github/skills/` content is AI-assisted development tooling: skills for auto-coding, QA, packaging, setup, and related workflows. These are not runtime components of the RAG server, but they do explain how the project is intended to be built, tested, and packaged.

Main entry points: [`src/mcp_server/server.py`](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/server.py) (MCP server), [`src/core/query_engine/hybrid_search.py`](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/hybrid_search.py) (Query engine), [`src/core/response/response_builder.py`](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/response/response_builder.py) (Response), [`src/ingestion/pipeline.py`](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/pipeline.py) (Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry points"]
  node_main_py(("main.py<br/>runtime entrypoint<br/>[main.py]"))
  node_script_ingest(("Ingest<br/>cli script<br/>[ingest.py]"))
  node_script_query(("Query<br/>cli script<br/>[query.py]"))
  node_script_evaluate(("Evaluate<br/>cli script<br/>[evaluate.py]"))
  node_script_dashboard(("Dashboard<br/>cli script<br/>[start_dashboard.py]"))
end

subgraph group_ingestion["Ingestion"]
  node_ingestion_pipeline["Pipeline<br/>ingestion workflow<br/>[pipeline.py]"]
  node_document_manager["Docs<br/>document orchestration"]
  node_chunking["Chunking<br/>text segmentation"]
  node_transforms["Transforms<br/>content enrichment<br/>[base_transform.py]"]
  node_embeddings["Embeddings<br/>embedding stage<br/>[batch_processor.py]"]
  node_storage["Storage<br/>index write path<br/>[vector_upserter.py]"]
end

subgraph group_retrieval["Retrieval and response"]
  node_query_engine["Query engine<br/>retrieval workflow<br/>[hybrid_search.py]"]
  node_query_processor["Query processing<br/>query normalization<br/>[query_processor.py]"]
  node_hybrid_search["Hybrid search<br/>retrieval orchestration<br/>[hybrid_search.py]"]
  node_fusion["Fusion<br/>[fusion.py]"]
  node_reranker["Reranker<br/>ranking stage<br/>[reranker.py]"]
  node_response_builder["Response<br/>answer assembly"]
  node_citation_generator["Citations<br/>citation assembly"]
  node_multimodal_assembler["Multimodal<br/>context assembly"]
end

subgraph group_providers["Providers"]
  node_llm_factory["LLMs<br/>provider factory<br/>[llm_factory.py]"]
  node_embedding_factory["Embeddings backends<br/>provider factory"]
  node_reranker_factory["Rerankers<br/>provider factory"]
  node_vector_store_factory["Vector store<br/>provider factory"]
end

subgraph group_mcp["MCP server"]
  node_mcp_server["MCP server<br/>protocol server<br/>[server.py]"]
  node_protocol_handler["Protocol"]
  node_tool_query["Ask hub<br/>mcp tool"]
  node_tool_list["List collections<br/>mcp tool"]
  node_tool_summary["Doc summary<br/>mcp tool"]
end

subgraph group_observability["Observability"]
  node_trace["Tracing<br/>trace capture<br/>[trace_collector.py]"]
  node_dashboard_app["Dashboard<br/>ui app<br/>[app.py]"]
  node_trace_service["Trace service<br/>dashboard service<br/>[trace_service.py]"]
  node_evaluation["Evaluation<br/>eval runner<br/>[eval_runner.py]"]
end

subgraph group_config["Config and prompts"]
  node_settings["Settings<br/>runtime config<br/>[settings.py]"]
  node_prompts["Prompts<br/>prompt assets"]
end

node_main_py -->|"serves"| node_mcp_server
node_main_py -->|"orchestrates"| node_ingestion_pipeline
node_script_ingest -->|"runs"| node_ingestion_pipeline
node_script_query -->|"runs"| node_query_engine
node_script_evaluate -->|"runs"| node_evaluation
node_script_dashboard -->|"starts"| node_dashboard_app
node_ingestion_pipeline -->|"loads"| node_document_manager
node_document_manager -->|"chunks"| node_chunking
node_document_manager -->|"enriches"| node_transforms
node_chunking -->|"feeds"| node_embeddings
node_transforms -->|"uses"| node_llm_factory
node_embeddings -->|"uses"| node_embedding_factory
node_ingestion_pipeline -->|"writes"| node_storage
node_storage -->|"uses"| node_vector_store_factory
node_storage -.->|"prepares"| node_query_engine
node_query_engine -->|"preprocesses"| node_query_processor
node_query_engine -->|"retrieves"| node_hybrid_search
node_hybrid_search -->|"combines"| node_fusion
node_hybrid_search -->|"refines"| node_reranker
node_hybrid_search -->|"selects"| node_reranker_factory
node_fusion -->|"supplies"| node_response_builder
node_response_builder -->|"adds"| node_citation_generator
node_response_builder -->|"merges"| node_multimodal_assembler
node_response_builder -->|"uses"| node_llm_factory
node_mcp_server -->|"speaks"| node_protocol_handler
node_mcp_server -->|"exposes"| node_tool_query
node_mcp_server -->|"exposes"| node_tool_list
node_mcp_server -->|"exposes"| node_tool_summary
node_tool_query -->|"calls"| node_query_engine
node_tool_list -->|"reads"| node_storage
node_tool_summary -->|"uses"| node_response_builder
node_trace -->|"feeds"| node_dashboard_app
node_trace_service -->|"queries"| node_trace
node_evaluation -.->|"consumes"| node_trace
node_settings -->|"configures"| node_ingestion_pipeline
node_settings -->|"configures"| node_query_engine
node_settings -->|"configures"| node_mcp_server
node_settings -->|"configures"| node_dashboard_app
node_prompts -->|"templates"| node_transforms
node_prompts -->|"templates"| node_reranker

click node_main_py "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/main.py"
click node_script_ingest "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/scripts/ingest.py"
click node_script_query "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/scripts/query.py"
click node_script_evaluate "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/scripts/evaluate.py"
click node_script_dashboard "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/scripts/start_dashboard.py"
click node_ingestion_pipeline "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/pipeline.py"
click node_document_manager "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/document_manager.py"
click node_chunking "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/chunking/document_chunker.py"
click node_transforms "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/transform/base_transform.py"
click node_embeddings "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/embedding/batch_processor.py"
click node_storage "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/storage/vector_upserter.py"
click node_query_engine "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/hybrid_search.py"
click node_query_processor "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/query_processor.py"
click node_hybrid_search "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/hybrid_search.py"
click node_fusion "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/fusion.py"
click node_reranker "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/reranker.py"
click node_response_builder "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/response/response_builder.py"
click node_citation_generator "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/response/citation_generator.py"
click node_multimodal_assembler "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/response/multimodal_assembler.py"
click node_llm_factory "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/libs/llm/llm_factory.py"
click node_embedding_factory "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/libs/embedding/embedding_factory.py"
click node_reranker_factory "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/libs/reranker/reranker_factory.py"
click node_vector_store_factory "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/libs/vector_store/vector_store_factory.py"
click node_mcp_server "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/server.py"
click node_protocol_handler "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/protocol_handler.py"
click node_tool_query "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/tools/query_knowledge_hub.py"
click node_tool_list "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/tools/list_collections.py"
click node_tool_summary "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/tools/get_document_summary.py"
click node_trace "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/trace/trace_collector.py"
click node_dashboard_app "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/observability/dashboard/app.py"
click node_trace_service "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/observability/dashboard/services/trace_service.py"
click node_evaluation "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/observability/evaluation/eval_runner.py"
click node_settings "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/settings.py"
click node_prompts "https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/config/prompts/chunk_refinement.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_py,node_script_ingest,node_script_query,node_script_evaluate,node_script_dashboard,node_settings,node_prompts toneBlue
class node_ingestion_pipeline,node_document_manager,node_chunking,node_transforms,node_embeddings,node_storage toneAmber
class node_query_engine,node_query_processor,node_hybrid_search,node_fusion,node_reranker,node_response_builder,node_citation_generator,node_multimodal_assembler toneMint
class node_llm_factory,node_embedding_factory,node_reranker_factory,node_vector_store_factory toneRose
class node_mcp_server,node_protocol_handler,node_tool_query,node_tool_list,node_tool_summary toneIndigo
class node_trace,node_dashboard_app,node_trace_service,node_evaluation toneTeal
```

## Components

### Entry points

Runtime scripts and app launchers

- [main.py](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/main.py): runtime entrypoint · Primary server launcher · `main.py`
- [Ingest](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/scripts/ingest.py): cli script · Bulk ingestion runner · `scripts/ingest.py`
- [Query](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/scripts/query.py): cli script · Ad hoc query runner · `scripts/query.py`
- [Evaluate](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/scripts/evaluate.py): cli script · Evaluation runner · `scripts/evaluate.py`
- [Dashboard](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/scripts/start_dashboard.py): cli script · Starts observability dashboard · `scripts/start_dashboard.py`

### Ingestion

Document-to-index pipeline

- [Pipeline](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/pipeline.py): ingestion workflow · Coordinates document ingestion · `src/ingestion/pipeline.py`
- [Docs](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/document_manager.py): document orchestration · Loads, validates, and manages source documents · `src/ingestion/document_manager.py`
- [Chunking](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/chunking/document_chunker.py): text segmentation · Splits documents into chunks · `src/ingestion/chunking/document_chunker.py`
- [Transforms](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/transform/base_transform.py): content enrichment · Refines chunks, enriches metadata, captions images · `src/ingestion/transform/base_transform.py`
- [Embeddings](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/embedding/batch_processor.py): embedding stage · Batches and encodes dense and sparse representations · `src/ingestion/embedding/batch_processor.py`
- [Storage](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/ingestion/storage/vector_upserter.py): index write path · Writes vectors, BM25, and image assets · `src/ingestion/storage/vector_upserter.py`

### Retrieval and response

Query-time relevance and answer assembly

- [Query engine](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/hybrid_search.py): retrieval workflow · Coordinates query processing and retrieval · `src/core/query_engine/hybrid_search.py`
- [Query processing](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/query_processor.py): query normalization · Prepares the user query for retrieval · `src/core/query_engine/query_processor.py`
- [Hybrid search](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/hybrid_search.py): retrieval orchestration · Runs dense and sparse retrieval before fusion · `src/core/query_engine/hybrid_search.py`
- [Fusion](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/fusion.py): rank fusion · Combines candidate lists with RRF · `src/core/query_engine/fusion.py`
- [Reranker](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/query_engine/reranker.py): ranking stage · Refines top candidates · `src/core/query_engine/reranker.py`
- [Response](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/response/response_builder.py): answer assembly · Builds final assistant response · `src/core/response/response_builder.py`
- [Citations](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/response/citation_generator.py): citation assembly · Attaches source references · `src/core/response/citation_generator.py`
- [Multimodal](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/response/multimodal_assembler.py): context assembly · Merges text and image-derived context · `src/core/response/multimodal_assembler.py`

### Providers

Pluggable backend adapters and factories

- [LLMs](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/libs/llm/llm_factory.py): provider factory · Selects text and vision model backends · `src/libs/llm/llm_factory.py`
- [Embeddings backends](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/libs/embedding/embedding_factory.py): provider factory · Selects dense embedding backends · `src/libs/embedding/embedding_factory.py`
- [Rerankers](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/libs/reranker/reranker_factory.py): provider factory · Selects reranking backends · `src/libs/reranker/reranker_factory.py`
- [Vector store](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/libs/vector_store/vector_store_factory.py): provider factory · Selects the vector database backend · `src/libs/vector_store/vector_store_factory.py`

### MCP server

Protocol boundary and exposed tools

- [MCP server](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/server.py): protocol server · Exposes RAG capability over MCP · `src/mcp_server/server.py`
- [Protocol](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/protocol_handler.py): mcp protocol · Handles MCP request/response flow · `src/mcp_server/protocol_handler.py`
- [Ask hub](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/tools/query_knowledge_hub.py): mcp tool · Knowledge query tool · `src/mcp_server/tools/query_knowledge_hub.py`
- [List collections](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/tools/list_collections.py): mcp tool · Enumerates available collections · `src/mcp_server/tools/list_collections.py`
- [Doc summary](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/mcp_server/tools/get_document_summary.py): mcp tool · Returns a document summary · `src/mcp_server/tools/get_document_summary.py`

### Observability

Tracing, dashboards, and evaluation

- [Tracing](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/trace/trace_collector.py): trace capture · Collects ingestion and query traces · `src/core/trace/trace_collector.py`
- [Dashboard](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/observability/dashboard/app.py): ui app · Streamlit dashboard shell · `src/observability/dashboard/app.py`
- [Trace service](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/observability/dashboard/services/trace_service.py): dashboard service · Reads and serves trace data · `src/observability/dashboard/services/trace_service.py`
- [Evaluation](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/observability/evaluation/eval_runner.py): eval runner · Runs composite and RAGAS evaluation · `src/observability/evaluation/eval_runner.py`

### Config and prompts

Runtime settings and prompt assets

- [Settings](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/src/core/settings.py): runtime config · Central runtime configuration · `src/core/settings.py`
- [Prompts](https://github.com/jerry-ai-dev/modular-rag-mcp-server/blob/main/config/prompts/chunk_refinement.txt): prompt assets · Templates for refinement, enrichment, captioning, reranking · `config/prompts/chunk_refinement.txt`

## Connections

- main.py → MCP server: serves · Launches the MCP-facing runtime
- main.py → Pipeline: orchestrates · Can initialize ingestion-related services
- Ingest → Pipeline: runs · Triggers document ingestion
- Query → Query engine: runs · Executes retrieval and answering
- Evaluate → Evaluation: runs · Launches evaluation jobs
- Dashboard → Dashboard: starts · Opens observability UI
- Pipeline → Docs: loads · Coordinates source document handling
- Docs → Chunking: chunks · Breaks documents into retrievable units
- Docs → Transforms: enriches · Applies refinement and metadata/image transforms
- Chunking → Embeddings: feeds · Produces text units for encoding
- Transforms → LLMs: uses · Captioning and enrichment depend on LLM backends
- Embeddings → Embeddings backends: uses · Selects embedding provider
- Pipeline → Storage: writes · Persists indexed content and assets
- Storage → Vector store: uses · Writes vectors through a pluggable store
- Storage → Query engine: prepares · Builds artifacts later consumed by retrieval
- Query engine → Query processing: preprocesses · Normalizes incoming queries
- Query engine → Hybrid search: retrieves · Runs the main retrieval flow
- Hybrid search → Fusion: combines · Merges dense and sparse candidates
- Hybrid search → Reranker: refines · Optionally reranks top results
- Hybrid search → Rerankers: selects · Chooses reranking backend
- Fusion → Response: supplies · Passes ranked chunks to answer assembly
- Response → Citations: adds · Attaches source references
- Response → Multimodal: merges · Combines textual and image context
- Response → LLMs: uses · Generates final answers with model backends
- MCP server → Protocol: speaks · Implements MCP protocol boundary
- MCP server → Ask hub: exposes · Publishes knowledge query tool
- MCP server → List collections: exposes · Publishes collection listing tool
- MCP server → Doc summary: exposes · Publishes document summary tool
- Ask hub → Query engine: calls · Tool routes into retrieval workflow
- List collections → Storage: reads · Lists indexed collections
- Doc summary → Response: uses · Summarizes document content via response assembly
- Tracing → Dashboard: feeds · Dashboard reads trace data
- Trace service → Tracing: queries · Dashboard service accesses trace records
- Evaluation → Tracing: consumes · Evaluation can reuse trace and run data
- Settings → Pipeline: configures · Controls ingestion behavior
- Settings → Query engine: configures · Controls retrieval behavior
- Settings → MCP server: configures · Controls server/runtime options
- Settings → Dashboard: configures · Controls dashboard behavior
- Prompts → Transforms: templates · Supplies refinement and caption prompts
- Prompts → Reranker: templates · Supplies reranking prompt templates
