.topK) );

const rawResults = this.config.enableParallelRetrieval
  ? await Promise.all(retrievalPromises)
  : (await Promise.all(retrievalPromises)).flat();

const merged = this.deduplicate(rawResults.flat());
return {
  documents: merged.slice(0, this.config.topK),
  strategy: 'multi_query',
  latencyMs: performance.now() - start
};

}

async executeHyDE(originalQuery: string): Promise<TransformationResult> { const start = performance.now();

const prompt = `Construct a concise, technically accurate hypothetical answer to the following question. 
This response will be embedded for vector retrieval and must mirror the style and terminology of domain documentation.
Length: 80-120 words. Do not include disclaimers or meta-commentary.
Question: ${originalQuery}`;

const hypotheticalAnswer = await this.llm.generate(prompt);
const queryVector = await this.embedder.embed(hypotheticalAnswer);

const documents = await this.vectorStore.searchByVector(queryVector, this.config.topK);

return {
  documents,
  strategy: 'hyde',
  latencyMs: performance.now() - start
};

}

async executeDecomposition(originalQuery: string): Promise<TransformationResult> { const start = performance.now();

const prompt = `Decompose the following complex query into independent sub-questions. 
Each sub-question must be self-contained and retrievable without external context.
Output one sub-question per line. No numbering, no explanations.
Query: ${originalQuery}`;

const subQueries = (await this.llm.generate(prompt))
  .split('\n')
  .map(q => q.trim())
  .filter(q => q.length > 0);

const retrievalPromises = subQueries.map(sq =>
  this.vectorStore.similaritySearch(sq, this.config.topK)
);

const rawResults = this.config.enableParallelRetrieval
  ? await Promise.all(retrievalPromises)
  : (await Promise.all(retrievalPromises)).flat();

const merged = this.deduplicate(rawResults.flat());
return {
  documents: merged.slice(0, this.config.topK),
  strategy: 'decomposition',
  latencyMs: performance.now() - start
};

}

private deduplicate(documents: Document[]): Document[] { const seen = new Set<string>(); return documents.filter(doc => { const hash = this.computeContentHash(doc.content); if (seen.has(hash)) return false; seen.add(hash); return true; }); }

private computeContentHash(content: string): string { return Buffer.from(content.toLowerCase().replace(/\s+/g, ' ').trim()) .toString('base64') .slice(0, 16); } }

### Why This Architecture Works
- **Parallel Execution**: `Promise.all` ensures multi-query and decomposition strategies don't suffer from sequential API latency. Vector stores handle concurrent requests efficiently.
- **Deterministic Deduplication**: Base64 content hashing prevents duplicate chunks from consuming context window tokens. This is critical when multiple vectors retrieve overlapping document segments.
- **Strategy Agnosticism**: The engine returns a uniform `TransformationResult` interface. Downstream generators don't need to know which transformation was applied. This enables seamless A/B testing and routing logic.
- **Embedding Consistency**: HyDE explicitly reuses the document embedder. Mixing models introduces distribution shift that breaks cosine similarity assumptions.

## Pitfall Guide

### 1. Blind Strategy Stacking
**Explanation**: Combining HyDE, multi-query, and decomposition in a single pipeline multiplies LLM calls and retrieval operations. On a 100k document corpus, this can push latency past 3 seconds and inflate API costs by 400%.
**Fix**: Implement a query router that selects a single strategy based on intent complexity. Use lightweight classification (e.g., regex + small LLM) to route before transformation.

### 2. HyDE Domain Drift
**Explanation**: The hypothetical answer generator may produce technically plausible but factually misaligned content if the prompt lacks domain constraints. The resulting vector drifts into irrelevant clusters.
**Fix**: Inject domain-specific terminology and style guidelines into the HyDE prompt. Add a validation step that checks embedding similarity against a known positive anchor before retrieval.

### 3. Decomposition Over-Fragmentation
**Explanation**: Breaking a query into too many sub-questions dilutes retrieval focus. The context window fills with marginally relevant snippets, reducing signal-to-noise ratio.
**Fix**: Cap decomposition at 3 sub-queries. Enforce a minimum semantic weight threshold. Merge closely related sub-queries before retrieval.

### 4. Deduplication Blindness
**Explanation**: Merging results from multiple vectors without deduplication causes duplicate chunks to occupy context tokens. The generator receives redundant information, increasing hallucination risk.
**Fix**: Always apply content-hash deduplication before context assembly. Preserve original metadata to track which strategy retrieved each chunk.

### 5. Latency Neglect in Sequential Pipelines
**Explanation**: Running transformations sequentially (LLM → embed → retrieve → LLM → embed → retrieve) creates compounding latency. User experience degrades rapidly above 1.5s.
**Fix**: Parallelize independent retrieval calls. Cache embedding results for identical queries. Use streaming responses where applicable.

### 6. Embedding Model Mismatch
**Explanation**: Using different embedding models for queries and documents breaks the shared vector space assumption. Cosine similarity becomes mathematically invalid.
**Fix**: Enforce a single embedding model across the entire pipeline. Validate model consistency during deployment checks.

### 7. Fixed Top-K Rigidity
**Explanation**: Hardcoding `k=5` ignores result density. Sparse queries return low-confidence matches, while dense queries return redundant top results.
**Fix**: Implement dynamic `k` based on similarity score thresholds. Drop results below a confidence floor. Scale `k` proportionally to corpus size.

## Production Bundle

### Action Checklist
- [ ] Route queries dynamically: Classify intent complexity before selecting a transformation strategy.
- [ ] Enforce embedding consistency: Verify query and document embedders are identical across all environments.
- [ ] Implement parallel retrieval: Use `Promise.all` or async workers for multi-query and decomposition paths.
- [ ] Apply deterministic deduplication: Hash content before context assembly to prevent token waste.
- [ ] Set latency budgets: Cap total transformation + retrieval time at 1.2s. Fallback to naive search on timeout.
- [ ] Monitor RAGAS metrics: Track context recall and precision weekly. Alert on >5% degradation.
- [ ] Cache transformation outputs: Store LLM-generated variants and hypothetical answers for identical queries.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Single-concept, conversational query | Multi-Query Variant | Stabilizes retrieval across lexical variance without distribution shift | +1 LLM call, +3 retrievals |
| Technical documentation, formal domain | HyDE | Bridges question-answer semantic gap, maximizes precision & faithfulness | +1 LLM call, +1 embedding |
| Multi-hop, synthesis-heavy query | Query Decomposition | Isolates independent intents, maximizes recall for complex topics | +1 LLM call, +2-3 retrievals |
| Low-latency requirement (<800ms) | Naive + Metadata Filter | Avoids transformation overhead; relies on index quality | Baseline |
| High-accuracy compliance domain | HyDE + Strict Validation | Ensures domain alignment before retrieval; reduces hallucination risk | +1 LLM call, +1 embedding, +validation step |

### Configuration Template

```typescript
// query-routing.config.ts
export const QueryRoutingConfig = {
  strategies: {
    multiQuery: {
      enabled: true,
      maxVariants: 3,
      topK: 5,
      parallel: true,
      latencyBudgetMs: 1200,
      fallback: 'naive'
    },
    hyde: {
      enabled: true,
      topK: 5,
      domainPrompt: 'Use precise technical terminology. Mirror documentation style.',
      latencyBudgetMs: 1000,
      fallback: 'multiQuery'
    },
    decomposition: {
      enabled: true,
      maxSubQueries: 3,
      topK: 4,
      parallel: true,
      latencyBudgetMs: 1500,
      fallback: 'hyde'
    }
  },
  routing: {
    complexityThreshold: 0.7, // LLM confidence score
    latencyCircuitBreaker: 1800,
    deduplication: {
      algorithm: 'base64-content-hash',
      enabled: true
    }
  }
};

Quick Start Guide

1. Install Dependencies: Add your vector store client, LLM provider SDK, and embedding model wrapper to your project. Ensure all components share the same authentication context.
2. Initialize the Engine: Instantiate QueryTransformationEngine with your LLM, embedder, vector store, and the configuration template above. Verify embedding model consistency.
3. Deploy the Router: Implement a lightweight intent classifier (regex + small LLM or embedding similarity) to route incoming queries to the appropriate strategy. Apply latency budgets and fallback logic.
4. Validate & Monitor: Run a benchmark set of 50-100 representative queries. Track context recall, precision, and latency. Adjust topK, deduplication thresholds, and routing weights based on observed performance. Integrate RAGAS metrics into your CI/CD pipeline for continuous validation.