asuc-octo
diff --git a/‎.env.template‎
Lines changed: 1 addition & 0 deletions b/‎.env.template‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎.github/workflows/cd-build.yaml‎
Lines changed: 3 additions & 2 deletions b/‎.github/workflows/cd-build.yaml‎
Lines changed: 3 additions & 2 deletions
diff --git a/‎.github/workflows/cd-deploy.yaml‎
Lines changed: 28 additions & 2 deletions b/‎.github/workflows/cd-deploy.yaml‎
Lines changed: 28 additions & 2 deletions
diff --git a/‎.github/workflows/cd-dev.yaml‎
Lines changed: 3 additions & 0 deletions b/‎.github/workflows/cd-dev.yaml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎.github/workflows/cd-stage.yaml‎
Lines changed: 3 additions & 0 deletions b/‎.github/workflows/cd-stage.yaml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎apps/backend/scripts/prepare-typedefs.js‎
Lines changed: 1 addition & 1 deletion b/‎apps/backend/scripts/prepare-typedefs.js‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎apps/backend/src/bootstrap/loaders/express.ts‎
Lines changed: 4 additions & 0 deletions b/‎apps/backend/src/bootstrap/loaders/express.ts‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎apps/backend/src/modules/catalog/controller.ts‎
Lines changed: 69 additions & 1 deletion b/‎apps/backend/src/modules/catalog/controller.ts‎
Lines changed: 69 additions & 1 deletion
diff --git a/‎apps/backend/src/modules/semantic-search/client.ts‎
Lines changed: 55 additions & 0 deletions b/‎apps/backend/src/modules/semantic-search/client.ts‎
Lines changed: 55 additions & 0 deletions
diff --git a/‎apps/backend/src/modules/semantic-search/controller.ts‎
Lines changed: 50 additions & 0 deletions b/‎apps/backend/src/modules/semantic-search/controller.ts‎
Lines changed: 50 additions & 0 deletions
@@ -4,6 +4,7 @@ URL=http://localhost:5001
 BACKEND_PATH=/api
 GRAPHQL_PATH=/graphql
 NODE_ENV=development
+SEMANTIC_SEARCH_URL=http://semantic-search:8000
 MONGODB_URI=mongodb://mongodb:27017/bt?replicaSet=rs0
 REDIS_URI=redis://redis:6379
 BACKEND_URL=http://backend:8080
 
@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        image: [backend, frontend, datapuller, ag-frontend, staff-frontend]
+        image: [backend, frontend, datapuller, semantic-search, ag-frontend, staff-frontend]
 
     steps:
       - name: Login to Docker Hub
@@ -33,7 +33,8 @@ jobs:
       - name: Build and Push
         uses: docker/build-push-action@v6
         with:
-          file: ./apps/${{ matrix.image }}/Dockerfile
+          context: "https://github.com/${{ github.repository }}.git#${{ github.sha }}${{ matrix.image == 'semantic-search' && ':apps/semantic-search' || '' }}"
+          file: ${{ matrix.image == 'semantic-search' && './Dockerfile' || format('./apps/{0}/Dockerfile', matrix.image) }}
           target: ${{ matrix.image }}-prod
           tags: ${{ secrets.DOCKER_USERNAME }}/bt-${{ matrix.image }}:${{ inputs.image_tag }}
           cache-from: |
 
@@ -43,6 +43,7 @@ jobs:
           host: ${{ secrets.SSH_HOST }}
           username: ${{ secrets.SSH_USERNAME }}
           key: ${{ secrets.SSH_KEY }}
+          command_timeout: 15m
           script: |
             set -e  # Exit immediately if a command fails
 
@@ -60,6 +61,7 @@ jobs:
             if [ $status = true ]; then
               kubectl rollout restart deployment ${{ inputs.name }}-backend
               kubectl rollout restart deployment ${{ inputs.name }}-frontend
+              kubectl rollout restart deployment ${{ inputs.name }}-semantic-search 2>/dev/null || true
             fi
 
             # Deploy staff dashboard if requested
@@ -84,10 +86,34 @@ jobs:
               kubectl rollout status --timeout=300s deployment bt-staff-frontend
             fi
 
-            # Check container status
-            kubectl rollout status --timeout=300s deployment ${{ inputs.name }}-backend
+            # Check container status with debugging on failure
+            if ! kubectl rollout status --timeout=300s deployment ${{ inputs.name }}-backend; then
+              echo "=== Backend deployment failed, collecting debug info ==="
+              kubectl -n bt get pods -l app.kubernetes.io/instance=${{ inputs.name }} -o wide
+              echo "=== Pod descriptions ==="
+              kubectl -n bt describe pods -l app.kubernetes.io/instance=${{ inputs.name }} | tail -200
+              echo "=== Pod logs ==="
+              kubectl -n bt logs -l app.kubernetes.io/instance=${{ inputs.name }} --tail=100 --all-containers=true 2>/dev/null || true
+              exit 1
+            fi
             kubectl rollout status --timeout=300s deployment ${{ inputs.name }}-frontend
 
+            # Semantic-search check (non-blocking, may take a while due to model loading)
+            echo "=== Checking semantic-search status ==="
+            kubectl -n bt get pods -l app.kubernetes.io/instance=${{ inputs.name }} | grep semantic || true
+
+            if kubectl rollout status --timeout=300s deployment ${{ inputs.name }}-semantic-search 2>/dev/null; then
+              echo "Semantic-search deployed successfully"
+            else
+              echo "Semantic-search still starting or failed"
+            fi
+
+            echo "=== Semantic-search logs ==="
+            kubectl -n bt logs -l app.kubernetes.io/instance=${{ inputs.name }},app.kubernetes.io/name=semantic-search --tail=100 2>/dev/null || echo "No logs available yet"
+
+            echo "=== Semantic-search pod describe ==="
+            kubectl -n bt describe pods -l app.kubernetes.io/instance=${{ inputs.name }},app.kubernetes.io/name=semantic-search 2>/dev/null | tail -50 || true
+
       - name: Output Summary
         run: |
           echo "# :white_check_mark: Deployment available at [${{ inputs.host }}](https://${{ inputs.host }})." >> $GITHUB_STEP_SUMMARY
 
@@ -93,6 +93,9 @@ jobs:
         backend:
           image:
             tag: '${{ needs.compute-sha.outputs.sha_short }}'
+        semanticSearch:
+          image:
+            tag: '${{ needs.compute-sha.outputs.sha_short }}'
         datapuller:
           suspend: true
           image:
 
@@ -34,6 +34,9 @@ jobs:
         backend:
           image:
             tag: latest
+        semanticSearch:
+          image:
+            tag: latest
         datapuller:
           image:
             tag: latest
 
@@ -11,7 +11,7 @@ const typedefFiles = fs.readdirSync(sourceDir)
   .sort();
 
 // Get all module directories from backend/src/modules (excluding non-module directories)
-const excludedDirs = ['cache', 'generated-types'];
+const excludedDirs = ['cache', 'generated-types', 'semantic-search'];
 const moduleDirs = fs.readdirSync(modulesDir, { withFileTypes: true })
   .filter(dirent => dirent.isDirectory() && !excludedDirs.includes(dirent.name))
   .map(dirent => dirent.name)
 
@@ -9,6 +9,7 @@ import { RedisClientType } from "redis";
 import { config } from "../../../../../packages/common/src/utils/config";
 import bannerRoutes from "../../modules/banner/routes";
 import routeRedirectRoutes from "../../modules/route-redirect/routes";
+import semanticSearchRoutes from "../../modules/semantic-search/routes";
 import staffRoutes from "../../modules/staff/routes";
 import targetedMessageRoutes from "../../modules/targeted-message/routes";
 import passportLoader from "./passport";
@@ -78,6 +79,9 @@ export default async (
     targetedMessageRoutes(root, redis);
   }
 
+  // load semantic search routes
+  app.use("/semantic-search", semanticSearchRoutes);
+
   // load staff routes
   staffRoutes(app);
 
 
@@ -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,
 
@@ -0,0 +1,55 @@
+import { config } from "../../../../../packages/common/src/utils/config";
+
+interface SemanticSearchResult {
+  subject: string;
+  courseNumber: string;
+  title: string;
+  description: string;
+  score: number;
+  text: string;
+}
+
+interface SemanticSearchResponse {
+  query: string;
+  threshold: number;
+  count: number;
+  year: number;
+  semester: string;
+  allowed_subjects: string[] | null;
+  last_refreshed: string;
+  results: SemanticSearchResult[];
+}
+
+export async function searchSemantic(
+  query: string,
+  year: number,
+  semester: string,
+  allowedSubjects?: string[],
+  threshold: number = 0.3
+): Promise<SemanticSearchResponse> {
+  const url = `${config.semanticSearch.url}/search`;
+  const body = {
+    query,
+    threshold,
+    year,
+    semester,
+    allowed_subjects: allowedSubjects ?? null,
+  };
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    let detail: string | undefined;
+    try {
+      const body = await response.json();
+      detail = body?.detail ?? body?.error;
+    } catch {}
+    throw new Error(detail ?? `Semantic search service error: ${response.statusText}`);
+  }
+
+  return (await response.json()) as SemanticSearchResponse;
+}
@@ -0,0 +1,50 @@
+import { Request, Response } from "express";
+
+import { searchSemantic } from "./client";
+
+/**
+ * Lightweight semantic search endpoint that only returns course identifiers
+ * Frontend will use these to filter the already-loaded catalog
+ */
+export async function searchCourses(req: Request, res: Response) {
+  const { query, year, semester, threshold } = req.query;
+
+  if (!query || typeof query !== "string") {
+    return res.status(400).json({ error: "query parameter is required" });
+  }
+
+  const yearNum = year ? parseInt(year as string, 10) : undefined;
+  const semesterStr = semester as string | undefined;
+  const thresholdNum = threshold ? parseFloat(threshold as string) : 0.3;
+
+  try {
+    const results = await searchSemantic(
+      query,
+      yearNum!,
+      semesterStr!,
+      undefined,
+      thresholdNum
+    );
+
+    // Return lightweight response: only subject + courseNumber + score
+    const courseIds = results.results.map((r) => ({
+      subject: r.subject,
+      courseNumber: r.courseNumber,
+      score: r.score,
+    }));
+
+    return res.json({
+      query,
+      threshold: thresholdNum,
+      results: courseIds,
+      count: courseIds.length,
+    });
+  } catch (error) {
+    console.error("Semantic search error:", error);
+    return res.status(500).json({
+      error: "Semantic search failed",
+      results: [],
+      count: 0,
+    });
+  }
+}