Improve semantic score with chunk matching, MPNet, and calibration

Dockerfile

@@ -23,7 +23,7 @@ COPY --chown=user requirements.txt requirements.txt
 RUN pip install --no-cache-dir -r requirements.txt
 
 # Pre-download embedding model at build time (faster Space cold start)
-RUN su - user -c "python -c \"from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')\""
+RUN su - user -c "python -c \"from sentence_transformers import SentenceTransformer; SentenceTransformer('all-mpnet-base-v2')\""
 
 COPY --chown=user . /app
 

utilities/keyword_match.py

@@ -1,4 +1,7 @@
+import os
 import re
+
+import numpy as np
 from sklearn.metrics.pairwise import cosine_similarity
 from sentence_transformers import SentenceTransformer
 from utilities.skills import (
@@ -8,7 +11,13 @@ from utilities.skills import (
     clean_text,
 )
 
-model = SentenceTransformer("all-MiniLM-L6-v2")
+# MPNet is stronger than MiniLM for long-form resume/JD similarity.
+SEMANTIC_MODEL_ID = os.getenv("SEMANTIC_MODEL", "all-mpnet-base-v2")
+MAX_DOC_CHARS = 8000
+MAX_CHUNKS = 24
+MIN_CHUNK_CHARS = 35
+
+model = SentenceTransformer(SEMANTIC_MODEL_ID)
 
 
 # ---------------------------------------------------------------------------
@@ -35,20 +44,75 @@ STOP_WORDS: set = {
 # Text utilities
 # ---------------------------------------------------------------------------
 
+def truncate_text(text: str, max_chars: int = MAX_DOC_CHARS) -> str:
+    if len(text) <= max_chars:
+        return text
+    return text[:max_chars].rsplit(" ", 1)[0]
+
+
+def split_into_chunks(text: str, max_chunks: int = MAX_CHUNKS) -> list[str]:
+    """Split resume/JD into comparable segments (bullets, lines, sentences)."""
+    if not text:
+        return []
+
+    parts = re.split(r"[\n\r]+|(?<=[.!?])\s+", text)
+    chunks = [p.strip() for p in parts if len(p.strip()) >= MIN_CHUNK_CHARS]
+
+    if not chunks and text.strip():
+        words = text.split()
+        window = 55
+        for i in range(0, len(words), window):
+            piece = " ".join(words[i : i + window])
+            if len(piece) >= MIN_CHUNK_CHARS:
+                chunks.append(piece)
+
+    return chunks[:max_chunks]
+
+
 def extract_skill_sentences(text: str) -> str:
     """
-    Keep only sentences / bullet points that contain at least one
-    known tech skill. Falls back to the full text if nothing matches
-    (prevents a zero-length embedding).
+    Skill-heavy lines only — used as a secondary signal, not the main embedding.
     """
-    segments = re.split(r'[.\n;]', text)
-    cleaned_text = clean_text(text)
+    segments = re.split(r"[\n\r.;]+", text)
     relevant = []
     for seg in segments:
         seg_clean = clean_text(seg)
+        if len(seg_clean) < MIN_CHUNK_CHARS:
+            continue
         if any(skill in seg_clean for skill in SKILLS_SORTED_BY_LENGTH):
             relevant.append(seg_clean)
-    return " ".join(relevant) if relevant else cleaned_text
+    return " ".join(relevant) if relevant else clean_text(text)
+
+
+def calibrate_semantic_score(cosine: float) -> float:
+    """
+    Map raw cosine similarity to a 0–100 ATS-style scale.
+
+    MPNet/MiniLM cosine for related resume/JD pairs usually sits in ~0.35–0.82,
+    not 0.9+, so raw cosine understates good matches without calibration.
+    """
+    cosine = float(np.clip(cosine, 0.0, 1.0))
+    low, high = 0.32, 0.78
+    scaled = (cosine - low) / (high - low) * 100.0
+    return round(float(np.clip(scaled, 0.0, 100.0)), 2)
+
+
+def _pairwise_cosine(a: np.ndarray, b: np.ndarray) -> float:
+    return float(cosine_similarity([a], [b])[0][0])
+
+
+def _chunk_bidirectional_score(resume_chunks: list[str], jd_chunks: list[str]) -> float:
+    """How well JD requirements are covered by resume (and vice versa)."""
+    if not resume_chunks or not jd_chunks:
+        return 0.0
+
+    resume_emb = model.encode(resume_chunks, convert_to_numpy=True)
+    jd_emb = model.encode(jd_chunks, convert_to_numpy=True)
+    sim_matrix = cosine_similarity(resume_emb, jd_emb)
+
+    jd_coverage = float(sim_matrix.max(axis=0).mean())
+    resume_coverage = float(sim_matrix.max(axis=1).mean())
+    return (jd_coverage + resume_coverage) / 2.0
 
 
 def remove_stop_words(text: str) -> set:
@@ -92,19 +156,47 @@ def keyword_match_score(resume_text: str, jd_text: str) -> float:
 
 def semantic_match_score(resume_text: str, jd_text: str) -> float:
     """
-    Skill-focused semantic similarity.
+    Semantic similarity tuned for resume ↔ JD alignment.
 
-    Strategy:
-    - Filter both texts down to skill-relevant sentences before encoding.
-    - This focuses the embedding on technical content and reduces noise
-      from generic filler language ("we are a fast-paced team...").
+    Combines:
+    1. Full-document embedding (overall theme)
+    2. Chunk-level bi-directional match (handles length mismatch)
+    3. Skill-heavy lines (secondary boost)
+
+    Raw cosine is calibrated to a more intuitive 0–100 scale.
     """
-    resume_focused = extract_skill_sentences(resume_text)
-    jd_focused     = extract_skill_sentences(jd_text)
+    resume_clean = clean_text(resume_text)
+    jd_clean = clean_text(jd_text)
+
+    if not resume_clean or not jd_clean:
+        return 0.0
 
-    embeddings = model.encode([resume_focused, jd_focused])
-    score = cosine_similarity([embeddings[0]], [embeddings[1]])[0][0]
-    return round(float(score) * 100, 2)
+    resume_doc = truncate_text(resume_clean)
+    jd_doc = truncate_text(jd_clean)
+
+    doc_emb = model.encode([resume_doc, jd_doc], convert_to_numpy=True)
+    full_sim = _pairwise_cosine(doc_emb[0], doc_emb[1])
+
+    resume_chunks = split_into_chunks(resume_clean)
+    jd_chunks = split_into_chunks(jd_clean)
+    if len(resume_chunks) > 1 and len(jd_chunks) > 1:
+        chunk_sim = _chunk_bidirectional_score(resume_chunks, jd_chunks)
+    else:
+        chunk_sim = full_sim
+
+    resume_skills = extract_skill_sentences(resume_clean)
+    jd_skills = extract_skill_sentences(jd_clean)
+    if resume_skills and jd_skills:
+        skill_emb = model.encode(
+            [truncate_text(resume_skills, 4000), truncate_text(jd_skills, 4000)],
+            convert_to_numpy=True,
+        )
+        skill_sim = _pairwise_cosine(skill_emb[0], skill_emb[1])
+    else:
+        skill_sim = full_sim
+
+    raw_cosine = 0.30 * full_sim + 0.55 * chunk_sim + 0.15 * skill_sim
+    return calibrate_semantic_score(raw_cosine)
 
 
 def experience_level_penalty(resume_text: str, jd_text: str) -> float: