# RAG Pipeline Architecture > How source files become citation-bearing retrieval results for local agents without turning generated answers into source truth. Status: active · Kind: reference · Last verified: 2026-07-19 · Date: 2026-07-19 > Status: active > Last verified: 2026-07-19 (against the current AI platform overview, RAG service implementation, operations guide, and reranker decision record) > Scope: indexing, retrieval, provider boundaries, freshness, and failure behavior Retrieval-Augmented Generation (RAG) gives local agents a searchable view of project code, infrastructure documentation, and other approved knowledge sources. It returns inspectable source chunks with citations; it does not make the language model itself authoritative. This page documents the data flow and trust boundaries. Private hostnames, addresses, service endpoints, repository paths, source excerpts, and authentication details remain in internal operations documentation. --- ## Two separate pipelines Indexing turns source files into a searchable derived store. Querying retrieves relevant evidence from that store. Model inference happens after retrieval and remains a separate system. ```text approved read-only sources ↓ scan and filter language-aware chunking ↓ BGE-M3 embeddings ↓ project-scoped Qdrant collections agent query ↓ embed and search hybrid candidate retrieval ↓ optional reranking citation-bearing source chunks ↓ agent or model synthesis ``` Keeping these stages separate makes failures easier to identify. An indexing problem can create stale or missing evidence while inference remains healthy; an inference outage does not erase the searchable index. --- ## Indexing flow ### Source discovery and filtering The indexer scans an explicit set of approved source trees mounted read-only. It accepts documentation, code, configuration templates, and structured project metadata while excluding build output, dependency trees, caches, worktrees, archived noise, live environment files, and designated private content. Filtering is both a relevance control and a privacy boundary. It reduces duplicate or obsolete chunks and prevents known-sensitive trees from entering retrieval. It is not a substitute for keeping secrets out of source-controlled documents. ### Chunking Files are split according to their content type: - code and structured configuration use syntax-aware boundaries - prose uses overlapping sentence-oriented chunks - selected structured metadata is rendered into compact prose before embedding Each chunk retains project, file, and line metadata so a result can point back to the evidence that produced it. ### Embedding and storage BGE-M3 converts each chunk into a dense vector. Qdrant stores those vectors and their metadata in project-scoped collections. Sparse term matching is stored alongside dense similarity, allowing retrieval to combine semantic matches with exact technical vocabulary. Qdrant is a derived index, not the source of truth. If its stored vectors are lost or corrupted, they can be rebuilt from the approved source files. --- ## Query flow A normal project query follows these steps: 1. Scope the request to one project when the caller knows the authority boundary; otherwise use bounded cross-project search. 2. Embed the query with the same embedding family used for indexed chunks. 3. Retrieve a wider pool of dense and sparse candidates from Qdrant. 4. Fuse, filter, and deduplicate candidates while preserving source metadata. 5. Optionally apply a cross-encoder reranker. 6. Return a bounded list containing source text, file-and-line citation, relevance score, and metadata. Reranking is an optional stage, not a requirement for service availability. It remains disabled by default because measured trials did not justify its latency and quality cost. If an enabled reranker fails to load, retrieval continues through the normal non-reranked path and reports the degraded state operationally. --- ## Provider and access boundaries The RAG service owns scanning, indexing, embedding, vector search, and result construction. It does not own agent policy or final-answer generation. An authenticated MCP layer exposes narrow tools for project queries, host-context lookup, and cross-project search. This keeps agents from depending on the internal retrieval protocol and gives the integration boundary one place to enforce authentication, limits, and output formatting. Administrative actions such as forced indexing use a separate authenticated control path. Normal retrieval cannot silently become an indexing or deployment operation. ```text agent ↓ authenticated retrieval tool MCP provider boundary ↓ bounded query contract RAG service → Qdrant ↓ cited chunks agent decides how to use the evidence ``` The system is internal-only. Authentication protects the tool and administrative boundaries, while source filtering limits what can be indexed in the first place. --- ## Freshness model Incremental indexing runs on a schedule. File hashes allow unchanged content to be skipped, while changed files are re-chunked and their cached retrieval state is invalidated. Deletion handling removes stale file entries with safeguards against treating a damaged or incomplete source mount as a mass deletion. Freshness therefore has two clocks: 1. **Source freshness** — whether the underlying document reflects current reality. 2. **Index freshness** — whether the latest source version has completed an indexing cycle. A recent index cannot repair an outdated source document. Likewise, a correct source may not appear immediately after a change. Risky operational decisions should verify live state with live tools rather than treating indexed documentation as telemetry. A full rebuild is available for recovery or intentional index changes. It is an explicit administrative action, not part of a read-only query. --- ## Retrieved evidence is not a model-generated answer A retrieval result proves that a particular source chunk matched the query. Its citation makes that chunk inspectable. It does not prove that: - the source is current - the source is correct - the chunk contains enough context - the model interpreted it correctly - the generated answer stayed within the evidence For source-backed claims, the consumer should retain citations and prefer direct source inspection when the consequence is high. For current system state, live inventory, health, metrics, and logs outrank indexed documentation. Generated summaries may help a reader navigate, but they remain interpretations. They must not be fed back into the index as if they were independent source evidence, because that would create a synthesis feedback loop. --- ## Failure boundaries | Failure | Expected behavior | |---|---| | Source mount unavailable | Scheduled indexing skips or fails; the last completed index may remain queryable but becomes progressively stale | | Embedding model unavailable | New indexing and semantic queries fail readiness checks; existing vectors remain stored | | Qdrant unavailable | Retrieval fails even if source files and model inference remain healthy | | Optional reranker unavailable | Service continues on the verified non-reranked path and exposes the degraded condition | | Incremental index misses a change | Results remain stale until a later successful cycle or explicit rebuild | | Over-broad or low-quality retrieval | Citations expose the mismatch; retrieval-quality gates and source filtering guide correction | | MCP provider unavailable | Agent-facing tools fail even if the underlying RAG service remains healthy | | Language model unavailable | Citation-bearing retrieval may still work; answer synthesis does not | These boundaries keep recovery targeted. Rebuilding a vector collection should not require changing the inference lane, and restarting a model should not be mistaken for repairing stale evidence. --- ## Related documentation - [Local Inference Stack](/homelab/software/local-inference-stack) — model routing after retrieval - [Monitoring](/homelab/software/monitoring) — health, metrics, and alert boundaries - [Lab Philosophy](/homelab/philosophy) — authority and automation principles