AnishDev's picture
initial code and logic pushed
ff7b177
Raw History Blame Contribute Delete
21.5 kB
"""
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]