feat: refactor semantic serach to fit the new logic with pagination update from pine

Author: vaclisinc

apps/backend/src/modules/catalog/controller.ts

@@ -25,6 +25,7 @@ import {
 } from "@repo/common/models";
 
 import { getFields, hasFieldPath } from "../../utils/graphql";
+import { searchSemantic } from "../semantic-search/client";
 import { formatClass, formatSection } from "../class/formatter";
 import type { ClassModule } from "../class/generated-types/module-types";
 import { formatCourse } from "../course/formatter";
@@ -55,6 +56,7 @@ export interface CatalogQueryParams {
   sortOrder?: string | null;
   page?: number | null;
   pageSize?: number | null;
+  semanticSearch?: boolean | null;
 }
 
 type CatalogFilterCondition = Record<string, unknown>;
@@ -93,13 +95,26 @@ export const getCatalogSearch = async (params: CatalogQueryParams) => {
     sortOrder,
     page = 1,
     pageSize = 25,
+    semanticSearch,
   } = params;
 
   const effectivePage = Math.max(1, page ?? 1);
   const effectivePageSize = Math.min(100, Math.max(1, pageSize ?? 25));
   const skip = (effectivePage - 1) * effectivePageSize;
 
-  // If search is provided, use Atlas Search aggregation
+  // Semantic search branch — calls Python FAISS service
+  if (semanticSearch && search && search.trim().length > 0) {
+    return getCatalogWithSemanticSearch({
+      year,
+      semester,
+      searchTerm: search.trim(),
+      filters,
+      limit: effectivePageSize,
+      skip,
+    });
+  }
+
+  // If search is provided, use in-memory Fuse.js index
   if (search && search.trim().length > 0) {
     return getCatalogWithSearch({
       year,
@@ -130,6 +145,59 @@ export const getCatalogSearch = async (params: CatalogQueryParams) => {
   return { results, totalCount };
 };
 
+const getCatalogWithSemanticSearch = async ({
+  year,
+  semester,
+  searchTerm,
+  filters,
+  limit,
+  skip,
+}: {
+  year: number;
+  semester: string;
+  searchTerm: string;
+  filters: CatalogQueryParams["filters"];
+  limit: number;
+  skip: number;
+}) => {
+  // Throws if the semantic service is unavailable — surfaces as GraphQL error
+  const response = await searchSemantic(searchTerm, year, semester);
+
+  if (response.results.length === 0) {
+    return { results: [], totalCount: 0 };
+  }
+
+  // Throws if the semantic service is unavailable — surfaces as GraphQL error
+  // Python already returns results sorted by score descending — preserve that order.
+  // Build a rank map: "subject-courseNumber" → position in Python's ranked list
+  const rankMap = new Map<string, number>();
+  response.results.forEach(({ subject, courseNumber }, index) => {
+    rankMap.set(`${subject}-${courseNumber}`, index);
+  });
+
+  const query = buildFilterQuery(year, semester, filters);
+  query.$or = response.results.map(({ subject, courseNumber }) => ({
+    subject,
+    courseNumber,
+  })) as unknown as CatalogFilterCondition[];
+
+  // Fetch all matching docs — semantic result sets are small (bounded by threshold)
+  const allResults = await CatalogClassModel.find(query).lean();
+
+  // Sort by Python's relevance rank, then by section number within the same course
+  allResults.sort((a, b) => {
+    const rankA = rankMap.get(`${a.subject}-${a.courseNumber}`) ?? 999;
+    const rankB = rankMap.get(`${b.subject}-${b.courseNumber}`) ?? 999;
+    if (rankA !== rankB) return rankA - rankB;
+    return a.number.localeCompare(b.number);
+  });
+
+  const totalCount = allResults.length;
+  const results = allResults.slice(skip, skip + limit);
+
+  return { results, totalCount };
+};
+
 const getCatalogWithSearch = async ({
   year,
   semester,

apps/backend/src/modules/semantic-search/client.ts

@@ -36,30 +36,15 @@ export async function searchSemantic(
     allowed_subjects: allowedSubjects ?? null,
   };
 
-  try {
-    const response = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-    });
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
 
-    if (!response.ok) {
-      throw new Error(`Semantic search failed: ${response.statusText}`);
-    }
-
-    return (await response.json()) as SemanticSearchResponse;
-  } catch (error) {
-    console.error("Semantic search error:", error);
-    // Return empty results on error, gracefully falling back
-    return {
-      query,
-      threshold,
-      count: 0,
-      year,
-      semester,
-      allowed_subjects: allowedSubjects || null,
-      last_refreshed: new Date().toISOString(),
-      results: [],
-    };
+  if (!response.ok) {
+    throw new Error(`Semantic search service error: ${response.statusText}`);
   }
+
+  return (await response.json()) as SemanticSearchResponse;
 }

apps/frontend/src/components/ClassBrowser/Header/index.tsx

@@ -23,6 +23,7 @@ export default function Header() {
     setAiSearchActive,
     handleSemanticSearch,
     semanticLoading,
+    semanticError,
   } = useLayoutContext();
 
   const handleAiSearchSubmit = () => {
@@ -56,9 +57,7 @@ export default function Header() {
           autoFocus
           autoComplete="off"
         />
-        {!aiSearchActive && (
-          <div className={styles.label}>{classes.length.toLocaleString()}</div>
-        )}
+
         <IconButton
           className={classNames(styles.sparksButton, {
             [styles.active]: aiSearchActive,
@@ -78,6 +77,9 @@ export default function Header() {
           {semanticLoading ? "Searching..." : "Search with AI (Beta)  →"}
         </Button>
       )}
+      {aiSearchActive && semanticError && (
+        <div className={styles.semanticError}>{semanticError}</div>
+      )}
       {mode !== "full" && (
         <Button
           className={classNames(styles.filterButton, {

apps/frontend/src/components/ClassBrowser/context/LayoutContext.ts

@@ -13,6 +13,11 @@ export interface LayoutContextType {
   hasActiveFilters: boolean;
   semester: Semester;
   year: number;
+  aiSearchActive: boolean;
+  setAiSearchActive: (active: boolean) => void;
+  handleSemanticSearch: () => void;
+  semanticLoading: boolean;
+  semanticError: string | null;
 }
 
 export const LayoutContext = createContext<LayoutContextType | null>(null);

apps/frontend/src/components/ClassBrowser/hooks/useCatalogBrowser.ts

@@ -1,4 +1,4 @@
-import { useMemo } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 
 import { ITerm } from "@/lib/api";
 import { Semester } from "@/lib/generated/graphql";
@@ -22,6 +22,11 @@ export interface UseCatalogBrowserReturn {
   query: string;
   updateQuery: (q: string) => void;
   hasActiveFilters: boolean;
+  aiSearchActive: boolean;
+  setAiSearchActive: (active: boolean) => void;
+  handleSemanticSearch: () => void;
+  semanticLoading: boolean;
+  semanticError: string | null;
 }
 
 export default function useCatalogBrowser({
@@ -32,13 +37,34 @@ export default function useCatalogBrowser({
 }: UseCatalogBrowserOptions): UseCatalogBrowserReturn {
   const filterState = useCatalogFilters({ persistent });
 
+  // Semantic search state
+  const [aiSearchActive, setAiSearchActiveState] = useState(false);
+  // committedQuery is non-null only after the user has clicked "Search with AI"
+  const [committedQuery, setCommittedQuery] = useState<string | null>(null);
+
+  // Reset committed query when AI mode is turned off
+  useEffect(() => {
+    if (!aiSearchActive) setCommittedQuery(null);
+  }, [aiSearchActive]);
+
+  const setAiSearchActive = useCallback((active: boolean) => {
+    setAiSearchActiveState(active);
+  }, []);
+
+  const handleSemanticSearch = useCallback(() => {
+    setCommittedQuery(filterState.query);
+  }, [filterState.query]);
+
+  const isSemanticMode = aiSearchActive && committedQuery !== null;
+
   const queryResult = useCatalogQuery({
     year,
     semester,
-    query: filterState.query,
+    query: isSemanticMode ? committedQuery : filterState.query,
     sortBy: filterState.sortBy,
     effectiveOrder: filterState.effectiveOrder,
     filterVariables: filterState.filterVariables,
+    semanticSearch: isSemanticMode,
   });
 
   const filterContextValue: FilterContextType = useMemo(
@@ -94,5 +120,10 @@ export default function useCatalogBrowser({
     query: filterState.query,
     updateQuery: filterState.updateQuery,
     hasActiveFilters: filterState.hasActiveFilters,
+    aiSearchActive,
+    setAiSearchActive,
+    handleSemanticSearch,
+    semanticLoading: queryResult.loading && isSemanticMode,
+    semanticError: queryResult.semanticError,
   };
 }

apps/frontend/src/components/ClassBrowser/hooks/useCatalogQuery.ts

@@ -7,11 +7,10 @@ import type {
   ICatalogFilterOptions,
   ICatalogFilters,
 } from "@/lib/api/catalog";
-import {
-  GetCatalogFilterOptionsDocument,
-  GetCatalogSearchDocument,
-} from "@/lib/generated/graphql";
+import { GET_CATALOG_SEARCH } from "@/lib/api/catalog";
+import { GetCatalogFilterOptionsDocument } from "@/lib/generated/graphql";
 import type {
+  GetCatalogSearchQuery,
   GetCatalogSearchQueryVariables,
   Semester,
 } from "@/lib/generated/graphql";
@@ -56,6 +55,7 @@ export interface UseCatalogQueryOptions {
   sortBy: SortBy;
   effectiveOrder: "asc" | "desc";
   filterVariables: ICatalogFilters | undefined;
+  semanticSearch?: boolean;
 }
 
 export interface UseCatalogQueryReturn {
@@ -68,6 +68,7 @@ export interface UseCatalogQueryReturn {
   loadNextPage: () => Promise<void>;
   isLoadingNextPage: boolean;
   filterOptions: ICatalogFilterOptions | null;
+  semanticError: string | null;
 }
 
 export default function useCatalogQuery({
@@ -77,19 +78,25 @@ export default function useCatalogQuery({
   sortBy,
   effectiveOrder,
   filterVariables,
+  semanticSearch = false,
 }: UseCatalogQueryOptions): UseCatalogQueryReturn {
   const [localPage, setLocalPage] = useState(1);
   const [classes, setClasses] = useState<ICatalogClassServer[]>([]);
   const [isLoadingNextPage, setIsLoadingNextPage] = useState(false);
   const isLoadingNextPageRef = useRef(false);
   const queryGenerationRef = useRef(0);
 
-  // Use debounced search for the query
+  // In semantic mode the query is committed externally — no debounce needed.
+  // In normal mode, debounce to avoid firing on every keystroke.
   const [debouncedQuery, setDebouncedQuery] = useState(rawQuery);
   useEffect(() => {
+    if (semanticSearch) {
+      setDebouncedQuery(rawQuery);
+      return;
+    }
     const timer = setTimeout(() => setDebouncedQuery(rawQuery), 300);
     return () => clearTimeout(timer);
-  }, [rawQuery]);
+  }, [rawQuery, semanticSearch]);
 
   // Reset page when filters/search change
   useEffect(() => {
@@ -104,6 +111,7 @@ export default function useCatalogQuery({
     effectiveOrder,
     currentYear,
     currentSemester,
+    semanticSearch,
   ]);
 
   const catalogQueryVariables = useMemo<
@@ -116,6 +124,7 @@ export default function useCatalogQuery({
       filters: filterVariables,
       sortBy: debouncedQuery ? undefined : mapSortBy(sortBy),
       sortOrder: debouncedQuery ? undefined : mapSortOrder(effectiveOrder),
+      semanticSearch: semanticSearch || undefined,
     }),
     [
       currentYear,
@@ -124,11 +133,12 @@ export default function useCatalogQuery({
       filterVariables,
       sortBy,
       effectiveOrder,
+      semanticSearch,
     ]
   );
 
   // Server-side catalog query (always requests first page)
-  const { data, loading, fetchMore } = useQuery(GetCatalogSearchDocument, {
+  const { data, loading, error, fetchMore } = useQuery<GetCatalogSearchQuery, GetCatalogSearchQueryVariables>(GET_CATALOG_SEARCH, {
     variables: {
       ...catalogQueryVariables,
       page: 1,
@@ -203,6 +213,11 @@ export default function useCatalogQuery({
   }, [catalogQueryVariables, fetchMore, hasNextPage, loading, localPage]);
 
   const isFirstPageLoading = loading && localPage === 1 && !isLoadingNextPage;
+  const semanticError =
+    semanticSearch && error
+      ? (error.graphQLErrors[0]?.message ?? error.message ?? "AI search failed")
+      : null;
+
   return {
     classes,
     loading: isFirstPageLoading,
@@ -213,5 +228,6 @@ export default function useCatalogQuery({
     loadNextPage,
     isLoadingNextPage,
     filterOptions: filterOptionsData?.catalogFilterOptions ?? null,
+    semanticError,
   };
 }

apps/frontend/src/components/ClassBrowser/index.tsx

@@ -57,6 +57,11 @@ export default function ClassBrowser({
             hasActiveFilters: browser.hasActiveFilters,
             semester,
             year,
+            aiSearchActive: browser.aiSearchActive,
+            setAiSearchActive: browser.setAiSearchActive,
+            handleSemanticSearch: browser.handleSemanticSearch,
+            semanticLoading: browser.semanticLoading,
+            semanticError: browser.semanticError,
           }}
         >
           <div

apps/frontend/src/lib/api/catalog.ts

@@ -16,6 +16,7 @@ export const GET_CATALOG_SEARCH = gql`
     $sortOrder: SortOrder
     $page: Int
     $pageSize: Int
+    $semanticSearch: Boolean
   ) {
     catalogSearch(
       year: $year
@@ -26,6 +27,7 @@ export const GET_CATALOG_SEARCH = gql`
       sortOrder: $sortOrder
       page: $page
       pageSize: $pageSize
+      semanticSearch: $semanticSearch
     ) {
       results {
         year

packages/gql-typedefs/catalog.ts

@@ -205,6 +205,7 @@ export const catalogTypeDef = gql`
       sortOrder: SortOrder
       page: Int
       pageSize: Int
+      semanticSearch: Boolean
     ): CatalogResult!
 
     catalogClassIdentities(