Spaces:
Sleeping
Sleeping
Download app/pipeline/matcher.py from AnishDev/coderound-task-backend: direct link, hf CLI and curl.
- Browser
- Download file 21.5 kB
-
https://huggingface.co/spaces/AnishDev/coderound-task-backend/resolve/main/app/pipeline/matcher.py
- Command line
-
hf download hf://spaces/AnishDev/coderound-task-backend/app/pipeline/matcher.py
-
curl -L -o matcher.py https://huggingface.co/spaces/AnishDev/coderound-task-backend/resolve/main/app/pipeline/matcher.py
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] | |