refactor(search): clean up hybrid ranking logic and apply review feedback

Author: dfordp

apps/backend/src/utils/AI/askDocQuestion/askDocQuestion.ts

@@ -23,6 +23,9 @@ type VectorStoreEl = {
   docName: string;
 };
 
+type VectorStoreElWithSimilarity = VectorStoreEl & { similarity: number };
+
+
 /**
  * Simple in-memory vector store to hold document embeddings and their content.
  * Each entry contains:
@@ -274,19 +277,17 @@ export const searchChunkReference = async (
   query: string,
   maxResults: number = MAX_RELEVANT_CHUNKS_NB,
   minSimilarity: number = MIN_RELEVANT_CHUNKS_SIMILARITY
-): Promise<VectorStoreEl[]> => {
-  // Generate an embedding for the user's query
+): Promise<VectorStoreElWithSimilarity[]> => {
   const queryEmbedding = await generateEmbedding(query);
 
-  // Calculate similarity scores between the query embedding and each document's embedding
   const selection = vectorStore
     .map((chunk) => ({
       ...chunk,
-      similarity: cosineSimilarity(queryEmbedding, chunk.embedding), // Add similarity score to each doc
+      similarity: cosineSimilarity(queryEmbedding, chunk.embedding),
     }))
-    .filter((chunk) => chunk.similarity > minSimilarity) // Filter out documents with low similarity scores
-    .sort((a, b) => b.similarity - a.similarity) // Sort documents by highest similarity first
-    .slice(0, maxResults); // Select the top 6 most similar documents
+    .filter((chunk) => chunk.similarity > minSimilarity)
+    .sort((a, b) => b.similarity - a.similarity)
+    .slice(0, maxResults);
 
   const orderedDocKeys = new Set(selection.map((chunk) => chunk.fileKey));
 
@@ -300,8 +301,13 @@ export const searchChunkReference = async (
     )
   );
 
-  // Return the content of the top matching documents
-  return results;
+  return results.map((r) => ({
+    ...r,
+    similarity:
+      selection.find(
+        (s) => s.fileKey === r.fileKey && s.chunkNumber === r.chunkNumber
+      )?.similarity ?? 0,
+  }));
 };
 
 const CHAT_GPT_PROMPT = readAsset('./PROMPT.md');
@@ -401,3 +407,7 @@ export const askDocQuestion = async (
     relatedFiles,
   };
 };
+
+export function getEmbedding(input: string) {
+  throw new Error('Function not implemented.');
+}

apps/website/src/components/DocPage/Search/SearchView.tsx

@@ -16,23 +16,26 @@ import { useSearchParams } from 'next/navigation';
 import { useIntlayer, useLocale } from 'next-intlayer';
 import { type FC, useEffect, useRef, useState } from 'react';
 
+
 const fuseOptions: IFuseOptions<DocMetadata> = {
   includeScore: true,
   shouldSort: true,
-  threshold: 0.25, // More flexible fuzzy matching
-  ignoreLocation: true, // Word order insensitive
+  threshold: 0.25,
+  ignoreLocation: true,
   distance: 100,
   minMatchCharLength: 2,
   findAllMatches: true,
   keys: [
     { name: 'title', weight: 0.7 },
     { name: 'description', weight: 0.15 },
     { name: 'keywords', weight: 0.1 },
-    { name: 'excerpt', weight: 0.05 }, // Optional short snippet per doc
+    { name: 'excerpt', weight: 0.05 },
   ],
 };
 
-// Debounce utility
+const FUSE_WEIGHT = 0.3;
+const BACKEND_WEIGHT = 0.7;
+
 const debounce = <T extends (...args: any[]) => void>(
   func: T,
   delay: number,
@@ -48,16 +51,19 @@ const debounce = <T extends (...args: any[]) => void>(
   };
 };
 
+type BackendDocResult = { fileKey: string; similarityScore: number };
+
 function mergeHybridResults(
   fuseResults: Fuse.FuseResult<DocMetadata>[],
-  backendResults: { docKey: string; score: number }[],
+  backendResults: BackendDocResult[],
   allDocs: DocMetadata[]
 ): DocMetadata[] {
-  const normalizeFuse = (score?: number) => 1 - Math.min((score ?? 1) / 0.5, 1); // invert Fuse score
-  const normalizeBackend = (score: number) => Math.min(score / 1.0, 1); // already cosine-like
+  const normalizeFuse = (score?: number) =>
+    1 - Math.min((score ?? 1) / 0.5, 1); // invert Fuse score
+  const normalizeBackend = (score: number) => Math.min(score, 1); // no need to divide by 1
 
   const backendMap = new Map(
-    backendResults.map((r) => [r.docKey, normalizeBackend(r.score)])
+    backendResults.map((r) => [r.fileKey, normalizeBackend(r.similarityScore)])
   );
   const combinedMap = new Map<string, { doc: DocMetadata; score: number }>();
 
@@ -66,15 +72,15 @@ function mergeHybridResults(
     const fuseScore = normalizeFuse(fuseItem.score);
     const backendScore = backendMap.get(doc.docKey);
     const combinedScore = backendScore
-      ? 0.7 * backendScore + 0.3 * fuseScore
+      ? BACKEND_WEIGHT * backendScore + FUSE_WEIGHT * fuseScore
       : fuseScore;
     combinedMap.set(doc.docKey, { doc, score: combinedScore });
   }
 
-  for (const [docKey, backendScore] of backendMap) {
-    if (!combinedMap.has(docKey)) {
-      const doc = allDocs.find((d) => d.docKey === docKey);
-      if (doc) combinedMap.set(docKey, { doc, score: 0.7 * backendScore });
+  for (const [fileKey, backendScore] of backendMap) {
+    if (!combinedMap.has(fileKey)) {
+      const doc = allDocs.find((d) => d.docKey === fileKey);
+      if (doc) combinedMap.set(fileKey, { doc, score: BACKEND_WEIGHT * backendScore });
     }
   }
 
@@ -83,6 +89,7 @@ function mergeHybridResults(
     .map((entry) => entry.doc);
 }
 
+
 const SearchResultItem: FC<{ doc: DocMetadata; onClickLink: () => void }> = ({
   doc,
   onClickLink,
@@ -115,24 +122,28 @@ const SearchResultItem: FC<{ doc: DocMetadata; onClickLink: () => void }> = ({
   );
 };
 
+
+
 export const SearchView: FC<{
   onClickLink?: () => void;
   isOpen?: boolean;
 }> = ({ onClickLink = () => {}, isOpen = false }) => {
   const inputRef = useRef<HTMLInputElement>(null);
   const searchQueryParam = useSearchParams().get('search');
   const [results, setResults] = useState<DocMetadata[]>([]);
+  const [currentSearchQuery, setCurrentSearchQuery] = useState<string | null>(
+    searchQueryParam
+  );
+
   const { search, setSearch } = useSearch({
     defaultValue: searchQueryParam,
     onClear: () => setResults([]),
-    onSearch: (searchQuery: string) => {
-      const fuseSearchResults = fuse
-        .search(searchQuery)
-        .map((result) => result.item);
-
-      setResults(fuseSearchResults);
+    onSearch: (query) => {
+      const fuseResults = fuse.search(query).map((r) => r.item);
+      setResults(fuseResults);
     },
   });
+
   const { data: searchDocData, isFetching } = useSearchDoc({
     input: search,
   });
@@ -142,8 +153,8 @@ export const SearchView: FC<{
 
   const docMetadata = getIntlayer('doc-metadata', locale) as DocMetadata[];
   const blogMetadata = getIntlayer('blog-metadata', locale) as BlogMetadata[];
-
   const filesData = [...docMetadata, ...blogMetadata];
+
   const fuse = new Fuse(filesData, fuseOptions);
 
   const handleSearch = async (query: string) => {
@@ -166,16 +177,17 @@ export const SearchView: FC<{
 
   useEffect(() => {
     if (searchDocData?.data && currentSearchQuery) {
-      const backendDocsWithScore =
-        (searchDocData?.data ?? []).map((d: any) => ({
-          docKey: d.fileKey,
-          score: d.similarityScore ?? 0.5,
-        })) ?? [];
+      const backendDocumentsWithScore: BackendDocResult[] = searchDocData.data.map(
+        (doc) => ({
+          fileKey: doc.fileKey,
+          similarityScore: doc.similarityScore ?? 0.5,
+        })
+      );
 
-      const fuseSearchResults = fuse.search(currentSearchQuery);
+      const fuseResults = fuse.search(currentSearchQuery);
       const mergedResults = mergeHybridResults(
-        fuseSearchResults,
-        backendDocsWithScore,
+        fuseResults,
+        backendDocumentsWithScore,
         filesData
       );
 
@@ -184,24 +196,13 @@ export const SearchView: FC<{
   }, [searchDocData, currentSearchQuery, filesData, fuse]);
 
   useEffect(() => {
-    if (searchQuery) handleSearch(searchQuery);
-  }, [searchQuery]);
+    if (searchQueryParam) handleSearch(searchQueryParam);
+  }, [searchQueryParam]);
 
-  // Focus input when modal opens using setTimeout
-  // This waits for the browser's paint cycle and the modal animation
   useEffect(() => {
     if (isOpen) {
-      setTimeout(() => {
-        inputRef.current?.focus();
-      }, 50);
+      setTimeout(() => inputRef.current?.focus(), 50);
     }
-    return () => {
-      if (timeoutRef.current) clearTimeout(timeoutRef.current);
-    };
-  }, [isOpen]);
-
-  const isNoResult =
-    !isFetching && results.length === 0 && inputRef.current?.value !== '';
   }, [isOpen]);
 
   const isNoResult = !isFetching && results.length === 0 && search.length > 0;
@@ -228,10 +229,9 @@ export const SearchView: FC<{
 
         {results.length > 0 && (
           <ul className="flex flex-col gap-10">
-            {results.map((result, i) => (
+            {results.map((result) => (
               <li key={result.url}>
                 <SearchResultItem doc={result} onClickLink={onClickLink} />
-                <p className="text-gray-400 text-xs">Rank #{i + 1}</p>
               </li>
             ))}
           </ul>