B_URL! }); this.bm25Engine = new BM25Retriever(); this.reranker = new CrossEncoderReranker('cross-encoder/ms-marco-MiniLM-L-6-v2'); this.conflictResolver = new EntailmentChecker('roberta-large-mnli'); }

async executeQuery(userQuery: string): Promise<string> { // 1. Dual-path retrieval const vectorResults = await this.vectorSearch(userQuery); const keywordResults = await this.bm25Engine.search(userQuery);

// 2. Score fusion
const fusedCandidates = this.fuseScores(vectorResults, keywordResults);

// 3. Cross-encoder reranking
const reranked = await this.reranker.rerank(userQuery, fusedCandidates, this.config.rerankTopK);

// 4. Contradiction detection
const resolvedContext = await this.conflictResolver.filterConflicts(
  reranked, 
  this.config.contradictionThreshold
);

// 5. Grounded generation with citation enforcement
return this.generateWithValidation(userQuery, resolvedContext);

}

private fuseScores(vector: RetrievedChunk[], keywords: RetrievedChunk[]): RetrievedChunk[] { const merged = new Map<string, RetrievedChunk>(); [...vector, ...keywords].forEach(chunk => { const existing = merged.get(chunk.id); if (existing) { existing.score = this.config.hybridWeightVector * (existing.score > 0.5 ? existing.score : 0) + this.config.hybridWeightBM25 * (chunk.score > 0.5 ? chunk.score : 0); } else { merged.set(chunk.id, chunk); } }); return Array.from(merged.values()).sort((a, b) => b.score - a.score); }

private async generateWithValidation(query: string, context: RetrievedChunk[]): Promise<string> { const prompt = this.buildGroundedPrompt(query, context); let response = await this.callLLM(prompt);

// Citation validation loop
const citationMatches = response.match(this.config.citationRegex);
if (!citationMatches || citationMatches.length < 2) {
  const strictPrompt = prompt.replace('Answer concisely.', 'ERROR: Missing citations. Re-answer with explicit [src: page X] tags for every claim.');
  response = await this.callLLM(strictPrompt);
}

return response;

}

private buildGroundedPrompt(query: string, chunks: RetrievedChunk[]): string { const contextBlocks = chunks.map((c, i) => [src: ${c.metadata.pageIndex}] ${c.content} ).join('\n\n');

return `SYSTEM: You are a technical assistant. Answer ONLY using the provided context. 
Cite every factual claim using [src: page X]. If information is missing, state "Not covered in context."

CONTEXT:
${contextBlocks}

USER: ${query}
ASSISTANT:`;

}

private async callLLM(prompt: string): Promise<string> { // Implementation delegates to your preferred inference provider // Returns raw string response return ''; } }

### Architecture Decisions & Rationale
- **Why hybrid fusion over pure vector?** Embeddings normalize terminology, causing policy-specific terms like "Workday notification" or "Section 4.2" to lose weight. BM25 anchors lexical precision. The 0.6/0.4 split prioritizes semantic intent while preserving exact-match safety nets.
- **Why cross-encoder reranking?** Bi-encoders compute embeddings independently, losing interaction signals. Cross-encoders attend to query-chunk pairs jointly, catching contextual mismatches that cosine similarity misses. The latency cost is amortized across the top-20 candidates, not the entire corpus.
- **Why explicit contradiction resolution?** LLMs lack temporal awareness. Without version metadata and entailment checks, they treat all retrieved text as equally valid. Forcing temporal precedence prevents compliance violations.
- **Why citation parsing?** Grounding is only as strong as its verification. Programmatic citation validation creates a deterministic feedback loop that eliminates untraceable claims.

## Pitfall Guide

### 1. The Attention Sink (Lost-in-the-Middle)
**Explanation:** LLMs exhibit positional bias, heavily weighting the first and last tokens in a context window. Middle chunks containing critical exceptions or notification deadlines are frequently ignored.
**Fix:** Reorder retrieved chunks by relevance score descending, but explicitly inject positional awareness into the prompt. Instruct the model to scan all numbered sources. Alternatively, use sliding window attention or chunk summarization to compress middle content into high-signal headers.

### 2. Semantic Drift (High Cosine, Low Relevance)
**Explanation:** Embeddings measure distributional similarity, not functional equivalence. A query about "part-time return policies" may retrieve chunks about "intermittent leave" due to overlapping vocabulary, despite different operational rules.
**Fix:** Never rely on vector scores alone. Implement cross-encoder reranking as a mandatory post-processing step. Set a strict relevance threshold (e.g., `score < 0.75` drops the chunk) before generation.

### 3. Temporal Paradox (Version Conflicts)
**Explanation:** Policy documents undergo revisions. Old and new clauses coexist in the vector store. The retriever returns both, and the LLM synthesizes a hybrid answer that violates current compliance standards.
**Fix:** Embed version metadata at ingestion. Run pairwise NLI (Natural Language Inference) checks on retrieved sets. Automatically suppress older versions when contradiction probability exceeds `0.8`. Log conflicts for human review.

### 4. Citation Laundering
**Explanation:** Models learn to fabricate citations that look valid but point to non-existent pages or mismatched content. This creates false confidence in the output.
**Fix:** Implement strict regex parsing of citation tags. Cross-reference cited page numbers against the actual retrieved chunk metadata. Reject responses where citations don't map to the provided context. Retry with a penalty prompt.

### 5. Over-Retrieval Bloat
**Explanation:** Requesting too many chunks (e.g., top-20) floods the context window, increasing latency, cost, and noise. The model's attention dilutes across irrelevant passages.
**Fix:** Cap retrieval at `top-5` after reranking. Use dynamic chunk sizing based on query complexity. Monitor context utilization metrics and adjust `k` based on empirical precision curves.

### 6. Prompt Injection via Context
**Explanation:** Malicious or poorly formatted internal documents can contain instructions that override system prompts. LLMs treat context as authoritative, executing embedded commands.
**Fix:** Sanitize ingested text for instruction-like patterns. Use XML-style delimiters to separate context from instructions. Implement a content safety filter at the ingestion layer.

## Production Bundle

### Action Checklist
- [ ] Implement hierarchical document splitting with metadata attachment (version, timestamp, section path)
- [ ] Deploy hybrid retrieval combining vector embeddings and BM25 keyword matching
- [ ] Integrate cross-encoder reranking (`cross-encoder/ms-marco-MiniLM-L-6-v2`) as a mandatory post-retrieval step
- [ ] Add NLI-based contradiction detection (`roberta-large-mnli`) with version precedence logic
- [ ] Enforce citation parsing with programmatic validation and retry loops
- [ ] Set up evaluation harness (RAGAS/DeepEval) to track hallucination rate and citation accuracy
- [ ] Configure monitoring for retrieval latency, reranking throughput, and context window utilization
- [ ] Establish document versioning pipeline to automatically deprecate superseded chunks

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| High-compliance queries (HR, Legal, Finance) | Hybrid Search + Cross-Encoder Reranking + NLI Conflict Resolution | Maximizes precision and temporal accuracy; prevents policy violations | +40% compute cost, offset by reduced manual review |
| Internal developer runbooks | Vector Search + BM25 Fusion + Citation Enforcement | Balances speed and accuracy; developers tolerate minor noise if citations are present | Baseline cost |
| Customer-facing FAQ bot | Vector Search + Lightweight Reranker + Strict Grounding Prompt | Minimizes latency; prioritizes safety over exhaustive retrieval | -15% cost vs full pipeline |
| Real-time operational alerts | Keyword-First Retrieval + Template Generation | Low latency required; semantic nuance less critical than exact term matching | Lowest cost, highest speed |

### Configuration Template

```yaml
rag_pipeline:
  ingestion:
    chunk_strategy: hierarchical
    overlap_tokens: 128
    metadata_fields: [doc_id, version_hash, section_path, updated_at, page_index]
  
  retrieval:
    vector_model: text-embedding-3-small
    vector_dims: 1536
    bm25_k1: 1.2
    bm25_b: 0.75
    fusion_weights:
      vector: 0.6
      bm25: 0.4
    initial_top_k: 20
  
  reranking:
    model: cross-encoder/ms-marco-MiniLM-L-6-v2
    final_top_k: 5
    relevance_threshold: 0.75
  
  conflict_resolution:
    entailment_model: roberta-large-mnli
    contradiction_threshold: 0.8
    precedence_rule: version_hash_desc
  
  generation:
    citation_pattern: "\\[src:\\s*page\\s*(\\d+)\\]"
    max_retries: 2
    grounding_instruction: "Answer ONLY using provided context. Cite every claim."
  
  monitoring:
    metrics: [hallucination_rate, citation_accuracy, retrieval_latency, rerank_score_distribution]
    alert_threshold:
      hallucination_rate: 0.05
      retrieval_latency_ms: 300

Quick Start Guide

1. Initialize the Ingestion Layer: Set up a document parser that extracts text, splits hierarchically, and attaches version metadata. Push chunks to your vector store and BM25 index simultaneously.
2. Deploy the Retrieval Orchestrator: Instantiate the hybrid search pipeline with the provided configuration template. Test with 50 representative internal queries to calibrate fusion weights and reranking thresholds.
3. Activate Guardrails: Enable cross-encoder reranking and NLI contradiction detection. Run a validation suite comparing naive RAG outputs against the guardrailed pipeline. Verify citation parsing rejects ungrounded responses.
4. Ship to Staging: Route internal traffic through the pipeline. Monitor hallucination rate, latency, and citation accuracy. Adjust top_k and relevance thresholds based on telemetry.
5. Production Rollout: Enable automatic version deprecation and conflict logging. Integrate with your CI/CD pipeline to re-index documents on commit. Establish weekly evaluation runs to track grounding stability.