RUNAI / src /features.py
xPushkal's picture
Deploy Redrob candidate ranker (Streamlit sandbox)
c580de7
Raw History Blame Contribute Delete
14.1 kB
"""Per-candidate structured feature extraction.
Each candidate is reduced to a small set of interpretable components in [0,1]
(plus a behavioral multiplier and penalty/honeypot signals) that the scorer
combines. Every component is grounded in the JD (see src/jd.py) and the M1
findings (Docs/08_M1_Findings.md).
The structured features here are the *whole* ranker at M2 (no embeddings yet);
from M3 a semantic `relevance` term is blended in via src/score.py.
"""
from __future__ import annotations
from datetime import date, datetime
from . import jd
# Reference "today" for recency math (matches the dataset's recent activity window).
REFERENCE_DATE = date(2026, 6, 6)
PROFICIENCY_WEIGHT = {"beginner": 0.3, "intermediate": 0.6, "advanced": 0.85, "expert": 1.0}
# ---------------------------------------------------------------------------
# small helpers
# ---------------------------------------------------------------------------
def _lower(s) -> str:
return s.lower() if isinstance(s, str) else ""
def _parse_date(s):
if not s or not isinstance(s, str):
return None
try:
return datetime.strptime(s[:10], "%Y-%m-%d").date()
except ValueError:
return None
def _saturate(x: float, cap: float) -> float:
return min(1.0, x / cap) if cap > 0 else 0.0
def _months_between(a, b) -> int | None:
d1, d2 = _parse_date(a), _parse_date(b)
if not d1 or not d2:
return None
return (d2.year - d1.year) * 12 + (d2.month - d1.month)
def _any_term(text: str, terms) -> bool:
return any(t in text for t in terms)
# ---------------------------------------------------------------------------
# component features
# ---------------------------------------------------------------------------
def title_fit(c: dict) -> float:
"""How well the candidate's titles match the role. Best over current + history."""
titles = [_lower(c.get("profile", {}).get("current_title", ""))]
titles += [_lower(j.get("title", "")) for j in c.get("career_history", [])]
best = 0.05
for t in titles:
if not t:
continue
if _any_term(t, jd.STRONG_TITLE_TERMS):
best = max(best, 1.0)
elif _any_term(t, jd.ADJACENT_TITLE_TERMS):
best = max(best, 0.55)
elif _any_term(t, jd.ENG_TITLE_TERMS):
best = max(best, 0.30)
return best
def career_fit(c: dict) -> float:
"""Evidence in free-text that the candidate *built* relevant systems.
This is what lets a plain-language Tier-5 candidate surface even with a thin
skills list — and what keyword-stuffers (off-role descriptions) fail.
"""
blob = _lower(c.get("profile", {}).get("summary", ""))
for j in c.get("career_history", []):
blob += " " + _lower(j.get("description", ""))
hits = sum(1 for term in jd.CAREER_EVIDENCE_TERMS if term in blob)
return _saturate(hits, 4) # ~4 distinct evidence terms => full credit
def skill_trust(c: dict) -> tuple[float, list[str]]:
"""Corroborated AI-skill strength. Discounts keyword stuffing (0 endorsements,
0 duration, no assessment). Returns (trust in [0,1], top corroborated skill names).
"""
assessments = c.get("redrob_signals", {}).get("skill_assessment_scores", {}) or {}
scored = []
for s in c.get("skills", []):
name = s.get("name", "")
if _lower(name) not in jd.CORE_AI_SKILLS:
continue
prof = PROFICIENCY_WEIGHT.get(s.get("proficiency", ""), 0.3)
endorse = _saturate(s.get("endorsements", 0), 25)
dur = _saturate(s.get("duration_months", 0), 36)
if name in assessments:
assess = assessments[name] / 100.0
else:
assess = 0.55 # neutral when no assessment exists
corroboration = 0.34 * endorse + 0.33 * dur + 0.33 * assess
scored.append((prof * corroboration, name))
if not scored:
return 0.0, []
scored.sort(reverse=True)
# Sum of top corroborated skills, saturating (a coherent handful beats a long stuffed list).
trust = _saturate(sum(v for v, _ in scored[:5]) * 1.6, 3.0)
top_names = [n for _, n in scored[:3]]
return trust, top_names
def experience_fit(c: dict, cfg: dict) -> float:
yoe = c.get("profile", {}).get("years_of_experience", 0) or 0
lo = cfg["scoring"]["experience"]["ideal_min"]
hi = cfg["scoring"]["experience"]["ideal_max"]
falloff = cfg["scoring"]["experience"]["soft_falloff_years"]
if lo <= yoe <= hi:
return 1.0
dist = (lo - yoe) if yoe < lo else (yoe - hi)
return max(0.3, 1.0 - dist / falloff) # YOE is a guideline; keep a floor
def location_fit(c: dict, cfg: dict) -> float:
loc = cfg["scoring"]["location"]
country = _lower(c.get("profile", {}).get("country", ""))
if country == "india":
return loc["in_country_bonus"]
if c.get("redrob_signals", {}).get("willing_to_relocate"):
return loc["relocatable_bonus"]
return loc["out_of_scope"]
def behavior_modifier(c: dict, cfg: dict) -> float:
"""Bounded availability multiplier. -1 sentinels are treated as missing, not low."""
b = cfg["behavior_modifier"]
sig = c.get("redrob_signals", {})
quality = []
last = _parse_date(sig.get("last_active_date"))
if last:
days = (REFERENCE_DATE - last).days
if days <= 30:
quality.append(1.0)
elif days >= b["stale_days"]:
quality.append(0.2)
else:
quality.append(1.0 - 0.8 * (days - 30) / (b["stale_days"] - 30))
rr = sig.get("recruiter_response_rate")
if rr is not None:
quality.append(min(1.0, rr / 0.6)) # 0.6+ response rate is "good"
if sig.get("open_to_work_flag") is not None:
quality.append(1.0 if sig.get("open_to_work_flag") else 0.4)
notice = sig.get("notice_period_days")
if notice is not None:
quality.append(1.0 if notice <= 30 else max(0.4, 1.0 - (notice - 30) / 150))
icr = sig.get("interview_completion_rate")
if icr is not None and icr >= 0:
quality.append(icr)
if not quality:
return 1.0
q = sum(quality) / len(quality) # in [0,1]
return b["min"] + (b["max"] - b["min"]) * q
def negative_penalty(c: dict, cfg: dict) -> tuple[float, list[str]]:
"""Multiplicative penalty for JD 'do not want' signals. Expanded in M4.
Returns (penalty multiplier in (0,1], list of fired flags).
"""
pen = cfg["penalties"]
flags = []
mult = 1.0
companies = [_lower(j.get("company", "")) for j in c.get("career_history", [])]
companies.append(_lower(c.get("profile", {}).get("current_company", "")))
industries = [_lower(j.get("industry", "")) for j in c.get("career_history", [])]
industries.append(_lower(c.get("profile", {}).get("current_industry", "")))
# Consulting-only: every employer is a consulting firm, none product.
nonempty = [x for x in companies if x]
if nonempty and all(any(f in comp for f in jd.CONSULTING_FIRMS) for comp in nonempty):
flags.append("consulting_only")
mult *= pen["consulting_only"]
# CV/speech/robotics-primary WITHOUT NLP/IR exposure (JD do-not-want).
# Fire when vision/speech dominates the title or skills AND there is no core
# IR/NLP skill and no NLP/IR evidence in the career free-text.
title = _lower(c.get("profile", {}).get("current_title", ""))
skill_names = [_lower(s.get("name", "")) for s in c.get("skills", [])]
cv_skill_hits = sum(1 for s in skill_names if s in {t for t in jd.CV_SPEECH_ROBOTICS_TERMS})
cv_title = _any_term(title, jd.CV_SPEECH_ROBOTICS_TERMS)
core_hits = sum(1 for s in skill_names if s in jd.CORE_AI_SKILLS)
blob = _lower(c.get("profile", {}).get("summary", ""))
for j in c.get("career_history", []):
blob += " " + _lower(j.get("description", ""))
nlp_ir_evidence = any(t in blob for t in (
"nlp", "natural language", "retrieval", "search", "ranking", "recommend",
"embedding", "semantic", "information retrieval",
))
if (cv_title or cv_skill_hits >= 2) and core_hits == 0 and not nlp_ir_evidence:
flags.append("cv_speech_only")
mult *= pen["cv_speech_only"]
# Research-only career with no production deployment (JD disqualifier).
titles = [title] + [_lower(j.get("title", "")) for j in c.get("career_history", [])]
if titles and all(
(not t) or _any_term(t, jd.RESEARCH_ONLY_TERMS) for t in titles
) and any(_any_term(t, jd.RESEARCH_ONLY_TERMS) for t in titles):
if not any(w in blob for w in ("production", "deployed", "shipped", "users", "scale")):
flags.append("research_only")
mult *= pen["research_only"]
# LangChain-wrapper-only: LangChain present but no deeper IR/ranking signal.
if _any_term(blob + " " + " ".join(skill_names), jd.LANGCHAIN_TERMS) \
and core_hits <= 1 and not nlp_ir_evidence:
flags.append("langchain_only")
mult *= pen["langchain_only"]
# Title-chaser: many short stints (avg role tenure < 18 months over >= 4 roles).
ch = c.get("career_history", [])
if len(ch) >= 4:
durs = [j.get("duration_months", 0) for j in ch]
if durs and sum(durs) / len(durs) < 18:
flags.append("title_chaser")
mult *= pen["title_chaser"]
return mult, flags
def honeypot_signal(c: dict, cfg: dict) -> tuple[float, list[str]]:
"""Precision-first logical-consistency checks. Expanded in M4.
Returns (honeypot_score in [0,1], list of fired checks).
"""
p = c.get("profile", {})
yoe = p.get("years_of_experience", 0) or 0
skills = c.get("skills", [])
sig = c.get("redrob_signals", {})
ch = c.get("career_history", [])
total_career = sum(j.get("duration_months", 0) for j in ch)
flags = []
# Stated duration_months disagrees with the role's start/end dates (impossible).
# Note: the noisy checks `skill_gt_career` (9.2k hits) and `active_before_signup`
# (7.5k) were rejected in M4 calibration as data noise, not honeypot signal.
for j in ch:
dm = j.get("duration_months")
comp = _months_between(j.get("start_date"), j.get("end_date") or "2026-06-06")
if dm is not None and comp is not None and abs(dm - comp) > 6:
flags.append("dur_vs_dates")
break
for s in skills:
if s.get("proficiency") in ("expert", "advanced") and s.get("duration_months", 0) == 0:
flags.append("expert_0mo")
break
if total_career > yoe * 12 + 18:
flags.append("career_gt_yoe")
for j in ch:
if j.get("is_current") and j.get("duration_months", 0) > total_career + 1:
flags.append("currole_gt_career")
break
assessments = sig.get("skill_assessment_scores", {}) or {}
for s in skills:
if s.get("proficiency") == "expert" and s.get("name") in assessments \
and assessments[s["name"]] < 20:
flags.append("expert_lowassess")
break
for j in ch:
sd, ed = j.get("start_date"), j.get("end_date")
if sd and ed and sd > ed:
flags.append("start_gt_end")
break
score = min(1.0, 0.5 * len(flags)) # one strong flag = 0.5 (== threshold default)
return score, flags
# ---------------------------------------------------------------------------
# top-level extraction
# ---------------------------------------------------------------------------
def extract(c: dict, cfg: dict) -> dict:
"""Return all components plus raw facts (for reasoning) for one candidate."""
p = c.get("profile", {})
tf = title_fit(c)
cf = career_fit(c)
st, top_skills = skill_trust(c)
ef = experience_fit(c, cfg)
lf = location_fit(c, cfg)
bm = behavior_modifier(c, cfg)
pen, neg_flags = negative_penalty(c, cfg)
hp_score, hp_flags = honeypot_signal(c, cfg)
sig = c.get("redrob_signals", {})
# JD must-have evidence the candidate actually has (for reasoning — never invented).
skill_names = [s.get("name", "") for s in c.get("skills", [])]
skill_lower = {_lower(n): n for n in skill_names}
vector_db_skills = [skill_lower[k] for k in skill_lower if k in jd.VECTOR_DB_SKILLS]
eval_skills = [skill_lower[k] for k in skill_lower if k in jd.EVAL_SKILLS]
blob = _lower(p.get("summary", ""))
for j in c.get("career_history", []):
blob += " " + _lower(j.get("description", ""))
career_evidence = [t for t in jd.CAREER_EVIDENCE_TERMS if t in blob][:3]
gh = sig.get("github_activity_score")
return {
"candidate_id": c["candidate_id"],
"title_fit": tf,
"career_fit": cf,
"skill_trust": st,
"experience_fit": ef,
"location_fit": lf,
"behavior_mod": bm,
"penalty": pen,
"negative_flags": neg_flags,
"honeypot_score": hp_score,
"honeypot_flags": hp_flags,
# raw facts for reasoning / inspection (all drawn directly from the profile)
"facts": {
"current_title": p.get("current_title", ""),
"current_company": p.get("current_company", ""),
"current_industry": p.get("current_industry", ""),
"is_product": _lower(p.get("current_industry", "")) in jd.PRODUCT_INDUSTRIES,
"location": p.get("location", ""),
"country": p.get("country", ""),
"years_of_experience": p.get("years_of_experience", 0),
"top_skills": top_skills,
"vector_db_skills": vector_db_skills,
"eval_skills": eval_skills,
"career_evidence": career_evidence,
"recruiter_response_rate": sig.get("recruiter_response_rate"),
"last_active_date": sig.get("last_active_date"),
"open_to_work": sig.get("open_to_work_flag"),
"notice_period_days": sig.get("notice_period_days"),
"willing_to_relocate": sig.get("willing_to_relocate"),
"github_activity_score": gh if (gh is not None and gh >= 0) else None,
},
}