rate(userQuery, context); }

private reciprocalRankFusion( vectorDocs: Document[], bm25Docs: Document[], alpha: number ): Document[] { const scores = new Map<string, number>(); const k = 60; // RRF constant

// Score vector results
vectorDocs.forEach((doc, rank) => {
  const score = (1 - alpha) / (k + rank + 1);
  scores.set(doc.id, (scores.get(doc.id) || 0) + score);
});

// Score BM25 results
bm25Docs.forEach((doc, rank) => {
  const score = alpha / (k + rank + 1);
  scores.set(doc.id, (scores.get(doc.id) || 0) + score);
});

// Sort by fused score
return Array.from(scores.entries())
  .sort((a, b) => b[1] - a[1])
  .map(([id]) => this.findDocumentById(id));

}

private assembleContext(docs: Document[]): string { // Deduplication and metadata filtering logic here return docs.map(d => [Source: ${d.metadata.source}]\n${d.content}).join('\n\n'); } }

### 3. Architecture Decisions and Rationale

*   **Hybrid Search Default:** Vector search retrieves semantically similar text but fails on exact terms (e.g., SKU numbers, specific error codes). BM25 captures lexical matches. Combining them via Reciprocal Rank Fusion (RRF) mitigates the weaknesses of both. The `alpha` parameter allows tuning based on domain specificity; higher `alpha` favors keyword matching for technical documentation.
*   **Cross-Encoder Reranking:** Bi-encoders (used in vector search) compute embeddings independently, losing interaction details between query and document. Cross-encoders attend to the query-document pair simultaneously, providing a much more accurate relevance score. Reranking the top 50-100 candidates from hybrid search is computationally cheaper than running cross-encoders on the entire corpus and drastically improves Precision@K.
*   **Query Transformation:** Users rarely write queries optimized for retrieval. Rewriting queries to be more descriptive and expanding them into sub-queries handles ambiguity and multi-hop reasoning. For example, "How do I fix the API timeout?" should be rewritten to "API timeout error handling configuration retry logic."

## Pitfall Guide

Production RAG systems fail due to subtle architectural misalignments. Avoid these common mistakes.

1.  **Fixed-Size Chunking on Structured Data:**
    *   *Mistake:* Splitting documents by character count regardless of structure.
    *   *Impact:* Cuts tables, code blocks, or logical sections in half, destroying context.
    *   *Fix:* Use recursive character splitting that respects separators (headers, paragraphs). For code, use AST-based chunking. For PDFs, use layout-aware chunking.

2.  **Ignoring Metadata Filtering:**
    *   *Mistake:* Relying solely on semantic similarity for retrieval.
    *   *Impact:* Retrieving outdated documents or documents from irrelevant departments.
    *   *Fix:* Implement pre-filtering in the vector store. Embed metadata (dates, categories, access levels) and apply filters during the retrieval phase.

3.  **Context Window Overflow without Compression:**
    *   *Mistake:* Dumping all retrieved chunks into the prompt until the limit is reached.
    *   *Impact:* LLM attention dilution ("lost in the middle" phenomenon) and increased cost.
    *   *Fix:* Implement context compression. Summarize redundant chunks or use a secondary LLM call to extract only the most relevant sentences from retrieved documents.

4.  **Semantic Drift in Multi-Vector Indexes:**
    *   *Mistake:* Using different embedding models for indexing and querying without alignment.
    *   *Impact:* Vectors exist in different latent spaces, making similarity search meaningless.
    *   *Fix:* Enforce strict model versioning. Never mix embedding models in a single index without a projection layer.

5.  **Lack of Evaluation Loops:**
    *   *Mistake:* Relying on manual testing or anecdotal feedback.
    *   *Impact:* Regression in retrieval quality goes unnoticed as data changes.
    *   *Fix:* Integrate RAGAS or TruLens into the CI/CD pipeline. Measure Faithfulness, Answer Relevance, and Context Precision automatically on every data update.

6.  **Agentic Over-Engineering:**
    *   *Mistake:* Adding agents for query routing or self-correction when retrieval is the bottleneck.
    *   *Impact:* High latency, unpredictable behavior, and increased cost without solving the root cause.
    *   *Fix:* Optimize retrieval precision first. Agents should only be introduced for workflows requiring tool use, multi-step reasoning, or dynamic query decomposition that static transformation cannot handle.

7.  **Chunking Boundary Errors:**
    *   *Mistake:* No overlap between chunks.
    *   *Impact:* Information split across boundaries is lost during retrieval.
    *   *Fix:* Always implement chunk overlap (typically 10-15% of chunk size) to preserve context continuity.

## Production Bundle

### Action Checklist

- [ ] **Implement Hybrid Search:** Configure parallel vector and BM25 retrieval with RRF fusion.
- [ ] **Deploy Cross-Encoder Reranker:** Integrate a reranking model (e.g., BGE-Reranker, Cohere Rerank) for top-K candidates.
- [ ] **Define Adaptive Chunking:** Select chunking strategy based on document type (text, code, tables).
- [ ] **Enable Query Transformation:** Add rewriting and expansion steps to the query pipeline.
- [ ] **Add Metadata Filters:** Structure metadata schema and implement pre-filtering logic.
- [ ] **Setup Evaluation Metrics:** Instrument RAGAS or custom metrics for Precision, Recall, and Hallucination.
- [ ] **Implement Context Compression:** Add logic to filter redundant information before generation.
- [ ] **Monitor Latency Budget:** Ensure end-to-end latency stays within SLA; optimize reranker batch size.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Enterprise FAQ / Support** | Hybrid + Rerank | High precision on keywords and semantics; low latency required. | Low |
| **Legal / Compliance Docs** | Hybrid + Rerank + Metadata Filters | Exact term matching and date filtering are critical; hallucination cost is high. | Medium |
| **Complex Reasoning / Multi-hop** | Agentic RAG | Requires query decomposition and iterative retrieval to answer compound questions. | High |
| **Highly Relational Data** | GraphRAG | Leverages graph structure to answer queries spanning multiple entities; superior for "global" questions. | Medium-High |
| **Low-Latency Real-time Chat** | Naive Vector + Small Model | Latency constraints outweigh precision gains; use aggressive caching. | Low |

### Configuration Template

Use this YAML structure to parameterize your RAG system. This allows tuning without code changes.

```yaml
rag_pipeline:
  ingestion:
    chunking:
      strategy: "recursive" # recursive, semantic, markdown
      chunk_size: 512
      chunk_overlap: 64
      separators: ["\n\n", "\n", ". ", " "]
    embeddings:
      model: "text-embedding-3-large"
      dimensions: 1024
      batch_size: 100
  
  retrieval:
    hybrid:
      enabled: true
      vector_top_k: 50
      bm25_top_k: 50
      rrf_k: 60
      alpha: 0.7 # Weight for BM25 (0.0 to 1.0)
    reranking:
      enabled: true
      model: "bge-reranker-v2-m3"
      top_k: 10
      threshold: 0.65
    
  query:
    transformation:
      rewrite: true
      expand: true
      max_subqueries: 3
    
  generation:
    context_compression: true
    max_tokens: 1024
    temperature: 0.1

Quick Start Guide

1. Initialize Pipeline:

   npm install @codcompass/rag-core vector-store-client bm25-library
   

   Create a rag.config.yaml based on the template above.

2. Configure Ingestion: Set up your chunking strategy in the config. Run the ingestion script to process documents, extract metadata, and populate both the vector store and the inverted index for BM25.

3. Deploy Reranker: If using a local cross-encoder, spin up the inference service. If using an API, configure the API key and endpoint in your environment variables.

4. Run Evaluation: Before going live, run a benchmark dataset through the pipeline. Check Precision@5 and Context Recall. Adjust alpha and chunk_size if metrics are below thresholds.

5. Integrate and Monitor: Deploy the RAGOrchestrator class. Add logging for retrieval latency and reranker scores. Set up alerts for drops in retrieval precision or spikes in latency.