User query:    "my server keeps crashing during long AI sessions"
Documentation: "V8 heap exhaustion under concurrent LLM streaming connections"

Shared vocabulary: (none)
Dense similarity: ~0.62 (below threshold for confident retrieval)

// ✅ Query rewriter — aligns vocabulary to documentation style
// file: packages/db/src/retrieval/QueryTransformer.ts

import { generateObject } from 'ai'
import { createAnthropic } from '@ai-sdk/anthropic'
import { z } from 'zod'

const anthropic = createAnthropic()

const RewriteResultSchema = z.object({
  rewrittenQuery: z.string(),
  keywords: z.array(z.string()).max(5),
})

export async function rewriteQuery(
  userQuery: string,
  domainContext: string = 'Node.js, TypeScript, React, LLM streaming, RAG, vector databases',
): Promise<string> {
  const { object } = await generateObject({
    model: anthropic('claude-3-haiku-20240307'),
    schema: RewriteResultSchema,
    prompt: `Rewrite the following user question as a precise technical query using terminology 
appropriate for engineering documentation about: ${domainContext}.

User question: "${userQuery}"

Produce a concise technical rewrite (1-2 sentences) that would match the vocabulary used in 
technical documentation and code comments. Also list up to 5 key technical keywords.`,
  })

  // Combine rewritten query with keyword boosting for BM25
  return object.keywords.length > 0
    ? `${object.rewrittenQuery} ${object.keywords.join(' ')}`
    : object.rewrittenQuery
}

// ✅ HyDE — generate and embed a hypothetical answer
// file: packages/db/src/retrieval/HyDE.ts

import { generateText } from 'ai'
import { createAnthropic } from '@ai-sdk/anthropic'
import { embedAndNormalise } from '../embeddings'

const anthropic = createAnthropic()

export async function hydeEmbed(userQuery: string): Promise<number[]> {
  // Generate a hypothetical answer — quality intentionally modest to stay fast
  const { text: hypotheticalAnswer } = await generateText({
    model: anthropic('claude-3-haiku-20240307'),
    maxTokens: 300,  // Short answer — we're generating for embedding, not display
    temperature: 0.1,
    prompt: `Write a brief, factual technical answer (3-5 sentences) to this question as if 
you were writing documentation. Include technical terms. Question: "${userQuery}"`,
  })

  // Embed the hypothetical answer — its vector is closer to documentation vectors
  return embedAndNormalise(hypotheticalAnswer)
}

// ✅ Step-back: retrieve at a higher abstraction level
// file: packages/db/src/retrieval/StepBack.ts

import { generateText } from 'ai'
import { createAnthropic } from '@ai-sdk/anthropic'

const anthropic = createAnthropic()

export async function stepBack(specificQuery: string): Promise<string> {
  const { text } = await generateText({
    model: anthropic('claude-3-haiku-20240307'),
    maxTokens: 100,
    prompt: `Given this specific technical question, generate a more general/foundational 
question that would retrieve conceptual documentation useful for answering the specific question.

Specific: "${specificQuery}"
General (one sentence):`,
  })
  return text.trim()
}

// Example:
// Specific: "How do I set highWaterMark for pgvector HNSW index queries?"
// General:  "What are the HNSW indexing parameters in pgvector and how do they affect performance?"

// ✅ Multi-query decomposition — parallel retrieval, fused results
// file: packages/db/src/retrieval/MultiQueryDecomposer.ts

import { generateObject } from 'ai'
import { createAnthropic } from '@ai-sdk/anthropic'
import { z } from 'zod'
import { hybridSearch, HybridSearchResult } from './HybridSearch'

const anthropic = createAnthropic()

const DecomposedQueriesSchema = z.object({
  queries: z.array(z.string()).min(1).max(4),
})

export async function multiQueryRetrieve(
  orgId: string,
  userQuery: string,
  candidatesPerQuery = 20,
): Promise<HybridSearchResult[]> {
  // Decompose compound query into atomic sub-queries
  const { object } = await generateObject({
    model: anthropic('claude-3-haiku-20240307'),
    schema: DecomposedQueriesSchema,
    prompt: `Decompose the following question into 2-4 atomic sub-questions, each targeting 
a specific topic. Each sub-question should be independently answerable.

Question: "${userQuery}"`,
  })

  // Retrieve for all sub-queries in parallel
  const subResults = await Promise.all(
    object.queries.map(q => hybridSearch(orgId, q, candidatesPerQuery))
  )

  // Deduplicate by ID and apply RRF across sub-query result sets
  const seen = new Map<string, { result: HybridSearchResult; ranks: number[] }>()

  subResults.forEach((results, queryIdx) => {
    results.forEach((result, rank) => {
      const existing = seen.get(result.id)
      if (existing) {
        existing.ranks.push(rank)
      } else {
        seen.set(result.id, { result, ranks: [rank] })
      }
    })
  })

  // Compute RRF score across sub-query ranks
  const K = 60
  const merged = Array.from(seen.values()).map(({ result, ranks }) => ({
    ...result,
    rrfScore: ranks.reduce((sum, rank) => sum + 1 / (K + rank), 0),
  }))

  return merged.sort((a, b) => b.rrfScore - a.rrfScore)
}

// ✅ Adaptive query router — selects transformation strategy by query type
// file: packages/db/src/retrieval/QueryRouter.ts

import { rewriteQuery } from './QueryTransformer'
import { hydeEmbed } from './HyDE'
import { stepBack } from './StepBack'
import { multiQueryRetrieve } from './MultiQueryDecomposer'
import { hybridSearch } from './HybridSearch'
import { embedAndNormalise } from '../embeddings'

export type QueryStrategy = 'direct' | 'rewrite' | 'hyde' | 'multi-query'

export async function routeAndRetrieve(
  orgId: string,
  userQuery: string,
  strategy: QueryStrategy = 'rewrite',
  limit = 50,
) {
  switch (strategy) {
    case 'direct': {
      const embedding = await embedAndNormalise(userQuery)
      return hybridSearch(orgId, userQuery, limit)
    }
    case 'rewrite': {
      const rewritten = await rewriteQuery(userQuery)
      return hybridSearch(orgId, rewritten, limit)
    }
    case 'hyde': {
      // Use HyDE embedding for dense, original query for BM25
      const hydeEmbedding = await hydeEmbed(userQuery)
      // Custom hybrid search that accepts a pre-computed query embedding
      return hybridSearch(orgId, userQuery, limit, hydeEmbedding)
    }
    case 'multi-query': {
      return multiQueryRetrieve(orgId, userQuery, Math.ceil(limit / 3))
    }
  }
}