import type { StoredEmbedding } from "../store/embeddings"; const MIN_SIMILARITY = 0.3; const MIN_TOP_SCORE = 0.35; const SCORE_WINDOW = 0.08; const MAX_MATCHES = 8; const STOP_WORDS = new Set(["and", "for", "from", "into", "the", "tool", "tools", "with"]); export function rankBySimilarity( query: string, queryVector: number[], commands: StoredEmbedding[], ): string[] { return scoreAndFilterMatches(query, queryVector, commands).map((entry) => entry.name); } export function scoreAndFilterMatches( query: string, queryVector: number[], commands: StoredEmbedding[], ): Array<{ name: string; pathOrder: number; score: number }> { const queryMagnitude = vectorMagnitude(queryVector, "query"); const scored = commands .map((command) => ({ name: command.name, pathOrder: command.pathOrder, score: cosineSimilarity(queryVector, queryMagnitude, command), })) .sort((left, right) => { if (right.score !== left.score) { return right.score - left.score; } if (left.pathOrder !== right.pathOrder) { return left.pathOrder - right.pathOrder; } return left.name.localeCompare(right.name); }); const lexicalCandidates = filterByQueryTokens(query, scored, commands); const candidates = lexicalCandidates.length > 0 ? lexicalCandidates : scored; const bestScore = candidates[0]?.score; if (bestScore === undefined || bestScore < MIN_TOP_SCORE) { return []; } // Keep only the high-confidence cluster near the best hit instead of // returning the whole catalog in score order. const cutoff = Math.max(MIN_SIMILARITY, bestScore - SCORE_WINDOW); return candidates.filter((entry) => entry.score >= cutoff).slice(0, MAX_MATCHES); } function cosineSimilarity( queryVector: number[], queryMagnitude: number, command: StoredEmbedding, ): number { if (queryVector.length !== command.vector.length || queryVector.length === 0) { throw new Error(`embedding dimension mismatch for ${command.name}`); } const commandMagnitude = vectorMagnitude(command.vector, command.name); let dot = 0; for (let index = 0; index < queryVector.length; index += 1) { dot += queryVector[index]! * command.vector[index]!; } return dot / (queryMagnitude * commandMagnitude); } function vectorMagnitude(vector: number[], label: string): number { if (vector.length === 0) { throw new Error(`empty embedding vector for ${label}`); } let sum = 0; for (const value of vector) { sum += value * value; } if (sum === 0) { throw new Error(`zero-magnitude embedding vector for ${label}`); } return Math.sqrt(sum); } function filterByQueryTokens( query: string, scored: Array<{ name: string; pathOrder: number; score: number }>, commands: StoredEmbedding[], ): Array<{ name: string; pathOrder: number; score: number }> { const tokens = queryTokens(query); if (tokens.length === 0) { return []; } const commandText = new Map(commands.map((command) => [command.name, command.searchText])); const lexical = scored .map((entry) => ({ ...entry, overlap: overlapCount(tokens, commandText.get(entry.name)), })) .filter((entry) => entry.overlap > 0); const bestOverlap = lexical.reduce( (current, entry) => Math.max(current, entry.overlap), 0, ); if (bestOverlap === 0) { return []; } return lexical.filter((entry) => entry.overlap === bestOverlap); } function queryTokens(query: string): string[] { return query .toLowerCase() .split(/[^a-z0-9]+/) .filter((token) => token.length >= 3 && !STOP_WORDS.has(token)); } function overlapCount(tokens: string[], searchText?: string): number { if (searchText === undefined) { return 0; } return tokens.filter((token) => searchText.includes(token)).length; }