""" Core matching pipeline. Scoring weights: Skill matching 35% — proficiency-aware, no LLM Semantic (work) 40% — local embeddings (sentence-transformers) Position align 10% — current role vs JD title embedding Special 15% — GenAI depth (AI JDs) / stack alignment (Backend JDs) Penalties applied multiplicatively after weighted sum: years_slightly_below: ×0.85 (within 20% of threshold) years_unknown: ×0.95 engineer_type_unknown: ×0.90 work_exp_unavailable: ×0.95 skills_unavailable: ×0.80 Scale behaviour: ≤200 candidates : skip BM25, run full scoring >200 candidates : BM25 pre-filter to top 500, then full scoring """ import logging from typing import Optional import numpy as np from app.models.domain import ( CandidateData, JDRequirements, MatchResult, MatchTier, ScoreBreakdown, SkillMatchDetail, ) from app.pipeline import skill_parser, embedder as emb, bm25_filter from app.config import settings logger = logging.getLogger(__name__) # ─── Tier thresholds ────────────────────────────────────────────────────────── TIER_THRESHOLDS = [ (0.80, MatchTier.STRONG), (0.65, MatchTier.GOOD), (0.45, MatchTier.PARTIAL), (0.00, MatchTier.WEAK), ] def _get_tier(score: float) -> MatchTier: for threshold, tier in TIER_THRESHOLDS: if score >= threshold: return tier return MatchTier.WEAK # ─── Penalty constants ──────────────────────────────────────────────────────── PENALTY_YEARS_BELOW = 0.15 PENALTY_YEARS_UNKNOWN = 0.05 PENALTY_TYPE_UNKNOWN = 0.10 PENALTY_NO_WORK_EXP = 0.05 PENALTY_NO_SKILLS = 0.20 # ─── GenAI score lookup ─────────────────────────────────────────────────────── _GEN_AI_SCORE_MAP: dict[str, float] = { "2+ years": 1.0, "1.5 years - 2 years": 0.85, "1 to 1.5 years": 0.75, "6 months - 1 year": 0.60, "only internship/project experience": 0.40, "less than 6 months": 0.35, "i do not have gen ai experience": 0.10, } _GEN_AI_INFERENCE_KEYWORDS = { "rag", "llm", "vector", "embedding", "langchain", "langgraph", "openai", "anthropic", "generative", "gen ai", "genai", "huggingface", "transformer", "gpt", "claude", "gemini", "fine-tun", "prompt engineer", } def _score_gen_ai(candidate: CandidateData) -> float: """ Score GenAI experience with claim cross-validation. Problem: gen_ai_experience is self-reported. Candidates claim "2+ years" with zero LLM/RAG evidence in their actual work history. We now cross-validate the claim against work history evidence before trusting it. Evidence source: ONLY parsed_work_experience_text (not summary — summary is also a self-authored marketing document, same credibility problem). """ # Step 1: count GenAI keyword hits in WORK HISTORY only (not summary) work_text = candidate.parsed_work_experience_text.lower() work_evidence = sum(1 for kw in _GEN_AI_INFERENCE_KEYWORDS if kw in work_text) # Map work evidence hits → inferred score if work_evidence >= 4: inferred = 0.70 elif work_evidence >= 2: inferred = 0.50 elif work_evidence >= 1: inferred = 0.30 else: inferred = 0.10 # Step 2: look up self-reported claim raw = candidate.gen_ai_experience claimed = None if raw and raw.lower() not in ("none", "nan", ""): key = raw.strip().lower() if key in _GEN_AI_SCORE_MAP: claimed = _GEN_AI_SCORE_MAP[key] else: for k, v in _GEN_AI_SCORE_MAP.items(): if k in key or key in k: claimed = v break # Step 3: cross-validate claim vs evidence if claimed is not None: if work_evidence == 0: # Claim exists but ZERO work history evidence → claim is unverifiable # Use skills text as a weak corroboration signal skill_evidence = sum( 1 for kw in _GEN_AI_INFERENCE_KEYWORDS if kw in candidate.parsed_skills.lower() ) skill_inferred = 0.40 if skill_evidence >= 3 else (0.25 if skill_evidence >= 1 else 0.10) return skill_inferred # ignore the claim entirely elif work_evidence >= 3: # Strong work evidence → trust claim fully return claimed else: # Partial evidence → blend: 50% claim, 50% evidence return 0.50 * claimed + 0.50 * inferred # No claim field → pure inference (skills + work text) combined = work_text + " " + candidate.parsed_skills.lower() all_matches = sum(1 for kw in _GEN_AI_INFERENCE_KEYWORDS if kw in combined) if all_matches >= 4: return 0.70 if all_matches >= 2: return 0.50 if all_matches >= 1: return 0.30 return 0.10 # ─── Backend stack score ────────────────────────────────────────────────────── _BACKEND_CORE_SKILLS = {"nodejs", "node.js", "express", "expressjs"} _BACKEND_CLOUD = {"aws", "gcp", "azure"} _BACKEND_DB = {"postgresql", "mongodb", "mysql", "dynamodb", "redis"} _BACKEND_ARCH = {"microservices", "serverless", "rest apis", "api"} def _score_backend_stack(candidate: CandidateData) -> float: """Score stack alignment for backend JD.""" skill_names = {s.name for s in candidate.extracted_skills} combined = candidate.parsed_skills.lower() + " " + candidate.parsed_work_experience_text.lower() node_score = 1.0 if (skill_names & _BACKEND_CORE_SKILLS or "node" in combined) else 0.3 cloud_score = 0.8 if (skill_names & _BACKEND_CLOUD) else (0.4 if "cloud" in combined else 0.1) db_score = 0.8 if (skill_names & _BACKEND_DB) else 0.2 arch_score = 0.7 if (skill_names & _BACKEND_ARCH or "microservice" in combined) else 0.3 return 0.4 * node_score + 0.2 * cloud_score + 0.2 * db_score + 0.2 * arch_score # ─── Skill scoring ──────────────────────────────────────────────────────────── def _score_skills( jd: JDRequirements, candidate: CandidateData, ) -> tuple[float, list[SkillMatchDetail], list[SkillMatchDetail], list[str]]: """ Returns (skill_score, matched, below_level, missing_skill_names). Core logic: candidate_level >= jd_level → 1.0 candidate_level == jd_level - 1 → 0.6 candidate_level == jd_level - 2 → 0.2 candidate_level < jd_level - 2 → 0.05 skill absent from candidate → 0.0 Required skills weighted 3×, preferred 1×. """ if not candidate.extracted_skills: return 0.5, [], [], [] # Map normalized name → SkillEntry for fast lookup cand_map: dict[str, "SkillEntry"] = {s.name: s for s in candidate.extracted_skills} # Also index raw lowercased names for fuzzy matching cand_raw_map: dict[str, "SkillEntry"] = {} for s in candidate.extracted_skills: cand_raw_map[s.raw.lower()] = s # Required skills weight 3×, preferred 1×. # Deduplicate across lists — same skill in both required+preferred would score twice. # Keep the higher weight (required) when there's a conflict. _seen_jd: dict[str, float] = {} for s in jd.required_skills: _seen_jd[s.name] = max(_seen_jd.get(s.name, 0.0), 3.0) for s in jd.preferred_skills: if s.name not in _seen_jd: _seen_jd[s.name] = 1.0 # Rebuild lookup: name → SkillRequirement for the deduped set _jd_skill_map = {s.name: s for s in jd.required_skills} _jd_skill_map.update({s.name: s for s in jd.preferred_skills}) all_jd_skills = [ (_jd_skill_map[name], weight) for name, weight in _seen_jd.items() ] if not all_jd_skills: # No JD skills extracted → use semantic only return 0.5, [], [], [] total_weight = 0.0 weighted_score = 0.0 matched: list[SkillMatchDetail] = [] below_level: list[SkillMatchDetail] = [] missing: list[str] = [] for jd_skill, weight in all_jd_skills: jd_name = jd_skill.name jd_level = jd_skill.level # Find candidate skill (normalized name) cand_skill = cand_map.get(jd_name) # Try partial match on raw name if exact fails if cand_skill is None: for raw, cs in cand_raw_map.items(): if jd_name in raw or raw in jd_name: cand_skill = cs break if cand_skill is None: # Check if skill appears in work experience text (inferred) combined_lower = ( candidate.parsed_work_experience_text.lower() + " " + candidate.parsed_skills.lower() ) if jd_name in combined_lower or jd_skill.raw.lower() in combined_lower: # Inferred presence — give partial credit at default level level_diff = max(0, jd_level - 3) infer_score = max(0.0, 0.5 - 0.15 * level_diff) weighted_score += infer_score * weight total_weight += weight matched.append(SkillMatchDetail( skill=jd_name, candidate_level=3, required_level=jd_level, score=infer_score, status="inferred", )) else: missing.append(jd_name) total_weight += weight else: c_level = cand_skill.level level_diff = jd_level - c_level if level_diff <= 0: per_score = 1.0 status = "exceeded" if level_diff < 0 else "met" elif level_diff == 1: per_score = 0.60 status = "below_level" elif level_diff == 2: per_score = 0.20 status = "below_level" else: per_score = 0.05 status = "below_level" weighted_score += per_score * weight total_weight += weight detail = SkillMatchDetail( skill=jd_name, candidate_level=c_level, required_level=jd_level, score=per_score, status=status, ) if per_score >= 0.60: matched.append(detail) else: below_level.append(detail) skill_score = weighted_score / total_weight if total_weight > 0 else 0.5 return skill_score, matched, below_level, missing # ─── Semantic scoring ───────────────────────────────────────────────────────── def _score_semantic( jd_embedding: np.ndarray, candidate: CandidateData, candidate_embedding: np.ndarray, ) -> float: """Cosine similarity of JD vs candidate work+summary, normalized to [0,1].""" sim = emb.cosine_similarity(jd_embedding, candidate_embedding) return emb.normalize_similarity(sim) def _score_position( jd_title_embedding: np.ndarray, candidate: CandidateData, ) -> float: """Embed current_position + current_title, compare with JD title.""" pos_parts = [p for p in [candidate.current_position, candidate.current_title] if p] if not pos_parts: return 0.5 pos_text = " ".join(pos_parts) pos_emb = emb.embed_single(pos_text) sim = emb.cosine_similarity(jd_title_embedding, pos_emb) return emb.normalize_similarity(sim) # ─── Filters ────────────────────────────────────────────────────────────────── def _filter_by_type( jd: JDRequirements, candidates: list[CandidateData], ) -> list[CandidateData]: """Hard filter: exclude wrong engineer type. Include unknowns with flag.""" if not jd.engineer_type: return candidates # No type info — keep all kept: list[CandidateData] = [] for c in candidates: if c.engineer_type == jd.engineer_type: kept.append(c) elif "engineer_type_unknown" in c.flags or c.engineer_type == "Unknown": if "engineer_type_unknown" not in c.flags: c.flags.append("engineer_type_unknown") kept.append(c) # else: wrong type → excluded silently return kept def _filter_by_years( jd: JDRequirements, candidates: list[CandidateData], ) -> list[CandidateData]: """ Soft filter with 20% buffer. - Unknown (−1): include with penalty - Within 20% below threshold: include with penalty - Below 20% threshold: exclude """ if jd.min_years <= 0: return candidates threshold = jd.min_years buffer_min = threshold * 0.80 kept: list[CandidateData] = [] for c in candidates: yoe = c.years_of_experience if yoe == -1.0: if PENALTY_YEARS_UNKNOWN not in c.penalties: c.penalties.append(PENALTY_YEARS_UNKNOWN) if "years_unknown" not in c.flags: c.flags.append("years_unknown") kept.append(c) elif yoe >= threshold: kept.append(c) elif yoe >= buffer_min: if PENALTY_YEARS_BELOW not in c.penalties: c.penalties.append(PENALTY_YEARS_BELOW) if "years_slightly_below" not in c.flags: c.flags.append("years_slightly_below") kept.append(c) # else: too far below → excluded return kept # ─── Weight configuration ───────────────────────────────────────────────────── def _get_weights(jd: JDRequirements, candidate: CandidateData) -> dict[str, float]: """Return scoring weights based on JD type and data availability.""" has_skills = bool(candidate.extracted_skills) has_work = bool(candidate.parsed_work_experience_text.strip()) if not has_skills and not has_work: return {"skill": 0.0, "semantic": 0.70, "position": 0.15, "special": 0.15} if not has_work: return {"skill": 0.60, "semantic": 0.00, "position": 0.15, "special": 0.25} if not jd.required_skills: # Vague JD — lean on semantic return {"skill": 0.20, "semantic": 0.55, "position": 0.10, "special": 0.15} return {"skill": 0.35, "semantic": 0.40, "position": 0.10, "special": 0.15} # ─── Main matching function ─────────────────────────────────────────────────── def run_matching( jd: JDRequirements, candidates: list[CandidateData], top_n: int = 10, ) -> list[MatchResult]: """ Full pipeline: 1. Preprocess candidate skills 2. Hard filter: engineer_type 3. Hard filter: years_of_experience 4. BM25 pre-filter (if > threshold) 5. Embed JD + all candidates (batch) 6. Score each candidate 7. Sort + return top_n """ logger.info(f"Starting match: jd={jd.id}, candidates={len(candidates)}, top_n={top_n}") # ── Step 0: extract skills for each candidate ────────────────────────── for c in candidates: if not c.extracted_skills: c.extracted_skills = skill_parser.parse_skills_string(c.parsed_skills) c.extracted_skills = skill_parser.upgrade_levels_from_work_exp( c.extracted_skills, c.work_experiences ) if not c.extracted_skills and "skills_unavailable" not in c.flags: c.flags.append("skills_unavailable") c.penalties.append(PENALTY_NO_SKILLS) if not c.parsed_work_experience_text.strip() and "work_exp_unavailable" not in c.flags: c.flags.append("work_exp_unavailable") c.penalties.append(PENALTY_NO_WORK_EXP) # ── Step 1: hard filters ──────────────────────────────────────────────── filtered = _filter_by_type(jd, candidates) logger.info(f"After type filter: {len(filtered)}") filtered = _filter_by_years(jd, filtered) logger.info(f"After years filter: {len(filtered)}") if not filtered: logger.warning("No candidates passed filters") return [] # ── Step 2: BM25 pre-filter ───────────────────────────────────────────── if len(filtered) > settings.bm25_prefilter_threshold: filtered = bm25_filter.bm25_prefilter( jd.full_text, filtered, top_k=settings.bm25_top_k ) # ── Step 3: compute embeddings ────────────────────────────────────────── jd_content_text = f"{jd.title} {jd.full_text[:1500]}" jd_content_emb = emb.embed_single(jd_content_text) jd_title_emb = emb.embed_single(jd.title) # Semantic embedding uses WORK HISTORY only — it's evidence, not marketing. # Summary is a self-authored claim document; treating it equally to work # history lets candidates inflate scores by writing buzzwords in their bio. # Fallback to summary only when no work history exists (fresh grads, etc.) candidate_texts = [ c.parsed_work_experience_text.strip() or c.parsed_summary for c in filtered ] candidate_embeddings = emb.embed_texts(candidate_texts) # (N, 384) logger.info(f"Embeddings computed for {len(filtered)} candidates") # ── Step 4: score each candidate ──────────────────────────────────────── results: list[MatchResult] = [] is_ai_jd = jd.engineer_type == "AI Engineer" is_backend_jd = jd.engineer_type == "Backend Engineer" for i, candidate in enumerate(filtered): cand_emb = candidate_embeddings[i] # 4A: skill score skill_score, matched, below_level, missing = _score_skills(jd, candidate) # 4B: semantic score semantic_score = _score_semantic(jd_content_emb, candidate, cand_emb) # 4C: position score position_score = _score_position(jd_title_emb, candidate) # 4D: special score if is_ai_jd: special_score = _score_gen_ai(candidate) elif is_backend_jd: special_score = _score_backend_stack(candidate) else: # Unknown type — use position alignment again as tiebreaker special_score = position_score # 4E: weighted sum weights = _get_weights(jd, candidate) raw_score = ( weights["skill"] * skill_score + weights["semantic"] * semantic_score + weights["position"] * position_score + weights["special"] * special_score ) # 4F: apply penalties multiplicatively final_score = raw_score penalties_applied: list[dict] = [] for penalty in candidate.penalties: final_score *= (1 - penalty) penalties_applied.append({"factor": penalty, "effect": f"-{penalty*100:.0f}%"}) final_score = max(0.0, min(1.0, final_score)) tier = _get_tier(final_score) results.append(MatchResult( candidate_id=candidate.id, candidate_name=candidate.name, current_position=candidate.current_position, years_of_experience=candidate.years_of_experience, engineer_type=candidate.engineer_type, final_score=final_score, tier=tier, score_breakdown=ScoreBreakdown( skill_score=round(skill_score, 4), semantic_score=round(semantic_score, 4), position_score=round(position_score, 4), special_score=round(special_score, 4), final_score=round(final_score, 4), penalties_applied=penalties_applied, matched_skills=matched, below_level_skills=below_level, missing_skills=missing, ), flags=list(candidate.flags), notice_period=candidate.notice_period, most_recent_company=candidate.most_recent_company, )) # ── Step 5: sort and assign ranks ─────────────────────────────────────── results.sort(key=lambda r: r.final_score, reverse=True) for rank, result in enumerate(results[:top_n], start=1): result.rank = rank logger.info( f"Matching complete. Top scores: " f"{[round(r.final_score, 3) for r in results[:5]]}" ) return results[:top_n]