feat: implement matching router and stage 2 neural reranking logic

backend/src/matching/stage2.py

@@ -104,7 +104,7 @@ async def stage2_rerank(jd: dict, shortlist: list[dict]) -> list[dict]:
         passages.append(" ".join(parts) or "No profile text")
 
     from fastapi.concurrency import run_in_threadpool
-    from .reranker import rerank
+    from ..ml.reranker import rerank
     try:
         logger.info(f"[Stage 2] Starting neural reranking of {len(passages)} candidates...")
         reranker_scores = await run_in_threadpool(rerank, jd_query, passages)

backend/src/routers/matching.py

@@ -81,19 +81,24 @@ async def trigger_match(
     stage2_top_k: int = Query(100, description="How many Stage 1 candidates to pass to the neural reranker (Stage 2)"),
     db: AsyncSession = Depends(get_db),
 ):
-    jd = await _load_jd(jd_id, db)
-    qdrant = _get_qdrant(request)
-    jd_dict = _build_jd_dict(jd)
-    sid_str = str(session_id) if session_id else None
-
-    # Stage 1: Retrieve top-K from vector DB using composite weighted score
-    shortlist = await stage1_retrieve(jd_dict, db, qdrant, session_id=sid_str, top_k=stage1_top_k)
-    
-    # Stage 2: Run neural cross-encoder reranker on only the top stage2_top_k from Stage 1
-    rerank_input = shortlist[:stage2_top_k]
-    final_ranked = await stage2_rerank(jd_dict, rerank_input)
-
     try:
+        jd = await _load_jd(jd_id, db)
+        qdrant = _get_qdrant(request)
+        jd_dict = _build_jd_dict(jd)
+        sid_str = str(session_id) if session_id else None
+
+        # Stage 1: Retrieve top-K from vector DB
+        logger.info(f"[trigger_match] JD={jd_id} | Stage 1 starting (top_k={stage1_top_k})")
+        shortlist = await stage1_retrieve(jd_dict, db, qdrant, session_id=sid_str, top_k=stage1_top_k)
+        logger.info(f"[trigger_match] JD={jd_id} | Stage 1 complete — {len(shortlist)} candidates retrieved")
+
+        # Stage 2: Neural cross-encoder reranker
+        rerank_input = shortlist[:stage2_top_k]
+        logger.info(f"[trigger_match] JD={jd_id} | Stage 2 starting (reranking {len(rerank_input)} candidates)")
+        final_ranked = await stage2_rerank(jd_dict, rerank_input)
+        logger.info(f"[trigger_match] JD={jd_id} | Stage 2 complete — {len(final_ranked)} candidates ranked")
+
+        # Persist results to DB
         await db.execute(
             delete(MatchResult).where(
                 MatchResult.jd_id == jd_id,
@@ -118,14 +123,17 @@ async def trigger_match(
             inserted_mrs.append(mr)
 
         await db.commit()
+        logger.info(f"[trigger_match] JD={jd_id} | {len(inserted_mrs)} match results saved to DB")
+
     except Exception as exc:
-        logger.exception(f"[trigger_match] FATAL ERROR for JD {jd_id}: {exc}")
+        # Log the FULL traceback so it appears in HF container logs
+        logger.exception(f"[trigger_match] FATAL — JD={jd_id} session={session_id} | {type(exc).__name__}: {exc}")
         await db.rollback()
         raise
 
     from ..workers.explain import generate_top_explanations
 
-    # Pre-generate LLM explanations async for the top 20 matches implicitly in background
+    # Pre-generate LLM explanations async for top 20 in background
     top_20_ids = [str(mr.id) for mr in inserted_mrs[:20]]
     if top_20_ids:
         generate_top_explanations.delay(top_20_ids)