codebase-receipts-cli 1.0.0__py3-none-any.whl

receipts/ats/scorer.py

@@ -0,0 +1,550 @@
+"""Text-based ATS scorer — five dimensions, zero external dependencies.
+
+Scores a resume against a job description across:
+1. Keyword match (TF-IDF-style overlap)
+2. Action verb strength
+3. Quantification density
+4. Section completeness
+5. Brevity & formatting
+
+Works on .tex input directly (strips LaTeX → plain text → scores).
+No multimodal, no paid APIs, no spaCy/sklearn.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+
+from receipts.resume.tex_parser import ParsedResume, parse_resume
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class DimensionScore:
+    name: str
+    score: int  # 0–100
+    detail: str
+    weight: float = 1.0
+
+
+@dataclass(frozen=True)
+class BulletScore:
+    text: str
+    section: str
+    has_action_verb: bool
+    has_number: bool
+    word_count: int
+
+
+@dataclass(frozen=True)
+class ATSScore:
+    dimensions: list[DimensionScore]
+    bullet_scores: list[BulletScore]
+    composite: float
+    resume_name: str
+
+    def dimension(self, name: str) -> DimensionScore | None:
+        for d in self.dimensions:
+            if d.name == name:
+                return d
+        return None
+
+
+# ---------------------------------------------------------------------------
+# 1. Keyword match — TF-IDF-style overlap
+# ---------------------------------------------------------------------------
+
+_STOP_WORDS = frozenset(
+    "a an the and or but in on at to for of is it by with as from be was were "
+    "been are this that these those has have had do does did will would shall "
+    "should can could may might must not no nor so yet also very too each every "
+    "all any both few more most other some such than up out about into over "
+    "after before between through during above below under again further then "
+    "once here there when where why how what which who whom its our your their "
+    "he she we they i you me him her us them my his your our".split()
+)
+
+# Words that appear in virtually every job description and carry no signal —
+# counting them as "keywords" deflates every resume's score equally.
+_GENERIC_JD_WORDS = frozenset(
+    "software engineer engineers engineering developer developers development "
+    "experience experienced requirements required requirement skills skill "
+    "strong ability able working works building builds knowledge familiarity "
+    "familiar understanding proficiency proficient plus years year degree "
+    "bachelor bachelors master masters computer science looking join role "
+    "roles responsibilities responsibility qualifications qualification "
+    "preferred bonus candidate candidates position team teams communication "
+    "collaborative collaboration excellent solid hands-on hands passionate "
+    "environment fast-paced opportunity company related field equivalent "
+    "including etc write writing design designing develop developing "
+    "implement implementing maintain maintaining relevant technologies "
+    "technology tools tool best practices practice modern".split()
+)
+
+_TOKEN_RE = re.compile(r"[a-zA-Z][a-zA-Z0-9+#._-]{1,}")
+
+_KNOWN_TECH_TOKENS: frozenset[str] | None = None
+
+
+def _known_tech_tokens() -> frozenset[str]:
+    """Lowercased single tokens from the known-tech list, for boosting."""
+    global _KNOWN_TECH_TOKENS
+    if _KNOWN_TECH_TOKENS is None:
+        from receipts.resume.claim_extractor import KNOWN_TECH
+
+        tokens: set[str] = set()
+        for tech in KNOWN_TECH:
+            tokens.add(tech.lower())
+            for part in tech.lower().split():
+                tokens.add(part)
+        _KNOWN_TECH_TOKENS = frozenset(tokens)
+    return _KNOWN_TECH_TOKENS
+
+
+def _tokenize(text: str) -> list[str]:
+    # Trailing ./-/_ come from sentence punctuation ("skills.", "Docker,"),
+    # while internal ones are real ("node.js") — strip only the tail.
+    tokens = (t.lower().rstrip("._-") for t in _TOKEN_RE.findall(text))
+    return [t for t in tokens if t and t not in _STOP_WORDS]
+
+
+def _tf(tokens: list[str]) -> dict[str, float]:
+    counts = Counter(tokens)
+    total = len(tokens) or 1
+    return {t: c / total for t, c in counts.items()}
+
+
+def _idf(doc_tokens: list[list[str]]) -> dict[str, float]:
+    n = len(doc_tokens) or 1
+    df: Counter[str] = Counter()
+    for tokens in doc_tokens:
+        df.update(set(tokens))
+    return {t: math.log(n / (1 + count)) + 1 for t, count in df.items()}
+
+
+def _known_tech_phrases() -> list[str]:
+    """Multi-word tech terms ("Docker Compose", "Tailwind CSS"), lowercased."""
+    from receipts.resume.claim_extractor import KNOWN_TECH
+
+    return [t.lower() for t in KNOWN_TECH if " " in t]
+
+
+# Common multi-word JD requirements that aren't in the tech list but that
+# ATS systems match as phrases, not tokens.
+_JD_PHRASES = [
+    "rest apis",
+    "rest api",
+    "machine learning",
+    "deep learning",
+    "unit testing",
+    "system design",
+    "data structures",
+    "version control",
+    "code review",
+    "code reviews",
+    "vector databases",
+    "vector database",
+    "github actions",
+    "open source",
+]
+
+
+def _extract_jd_phrases(jd_lower: str) -> list[str]:
+    """Multi-word keywords found verbatim in the JD.
+
+    Longest-first so "rest apis" suppresses its substring "rest api".
+    """
+    candidates = sorted(set(_known_tech_phrases() + _JD_PHRASES), key=len, reverse=True)
+    found: list[str] = []
+    for phrase in candidates:
+        if phrase in jd_lower and not any(phrase in f for f in found):
+            found.append(phrase)
+    return found
+
+
+def _keyword_match_score(jd_text: str, resume_text: str) -> DimensionScore:
+    jd_tokens = _tokenize(jd_text)
+    resume_tokens = _tokenize(resume_text)
+
+    if not jd_tokens:
+        return DimensionScore("keyword_match", 50, "No JD keywords extracted.")
+
+    jd_lower = jd_text.lower()
+    resume_lower = resume_text.lower()
+
+    jd_tf = _tf(jd_tokens)
+    idf = _idf([jd_tokens, resume_tokens])
+    tech_tokens = _known_tech_tokens()
+
+    # Phrases are matched verbatim so "REST APIs" and "GitHub Actions"
+    # aren't shredded into meaningless single tokens.
+    phrases = _extract_jd_phrases(jd_lower)
+    phrase_parts = {part for p in phrases for part in p.split()}
+
+    jd_tfidf: dict[str, float] = {}
+    for t, tf in jd_tf.items():
+        if t in _GENERIC_JD_WORDS:
+            continue  # every JD says "software engineer, strong skills"
+        if t in phrase_parts:
+            continue  # covered by a phrase ("rest" inside "rest apis")
+        weight = tf * idf.get(t, 1)
+        if t in tech_tokens:
+            weight *= 2.5  # concrete tech terms are what ATS systems scan for
+        jd_tfidf[t] = weight
+
+    if not jd_tfidf and not phrases:
+        return DimensionScore("keyword_match", 50, "No specific JD keywords extracted.")
+
+    top_tokens = sorted(jd_tfidf, key=lambda t: jd_tfidf[t], reverse=True)
+    top_tokens = top_tokens[: max(0, 30 - len(phrases))]
+
+    # Weighted coverage: phrases count double — they're the highest-signal
+    # requirements a JD states.
+    matched_weight = 0.0
+    total_weight = 0.0
+    matched: list[str] = []
+    missing: list[str] = []
+
+    for phrase in phrases:
+        total_weight += 2.0
+        if phrase in resume_lower:
+            matched_weight += 2.0
+            matched.append(phrase)
+        else:
+            missing.append(phrase)
+
+    resume_set = set(resume_tokens)
+    for kw in top_tokens:
+        total_weight += 1.0
+        if kw in resume_set:
+            matched_weight += 1.0
+            matched.append(kw)
+        else:
+            missing.append(kw)
+
+    ratio = matched_weight / total_weight if total_weight else 0
+    # Real ATS screens treat ~70% keyword coverage as a strong match —
+    # a linear 0-100 ramp punished every realistic resume. Cap stays 100.
+    score = min(100, round(ratio * 115))
+
+    total_terms = len(phrases) + len(top_tokens)
+    missing_str = ", ".join(missing[:8])
+    detail = f"{len(matched)}/{total_terms} top JD keywords found."
+    if missing_str:
+        detail += f" Missing: {missing_str}"
+
+    return DimensionScore("keyword_match", score, detail, weight=2.0)
+
+
+# ---------------------------------------------------------------------------
+# 2. Action verb strength
+# ---------------------------------------------------------------------------
+
+_STRONG_VERBS = frozenset(
+    "architected automated built configured consolidated containerized created "
+    "debugged delivered deployed designed developed eliminated engineered "
+    "established executed expanded extracted founded generated implemented "
+    "improved increased integrated launched led maintained managed migrated "
+    "modernized monitored onboarded operated optimized orchestrated overhauled "
+    "pioneered productionized prototyped provisioned published rebuilt reduced "
+    "refactored released replaced resolved restructured revamped scaled secured "
+    "shipped simplified spearheaded standardized streamlined strengthened "
+    "supervised transformed troubleshot unified upgraded validated".split()
+)
+
+_WEAK_STARTERS = frozenset(
+    "assisted contributed experienced helped involved participated responsible "
+    "supported tasked utilized used worked".split()
+)
+
+
+_NEUTRAL_VERB_CREDIT = 0.4  # noun-led lines (skills rows) aren't weak, just neutral
+
+
+def _first_word(text: str) -> str:
+    words = text.strip().split()
+    return words[0].lower().rstrip(",.:;") if words else ""
+
+
+def _action_verb_score(bullets: list[BulletScore]) -> DimensionScore:
+    """Graded verb scoring: strong (1.0) / neutral (0.4) / weak starter (0.0).
+
+    Also penalizes leaning on the same strong verb over and over — three
+    bullets all starting with "Developed" read as template filler to both
+    ATS parsers and humans.
+    """
+    if not bullets:
+        return DimensionScore("action_verbs", 0, "No bullets found.")
+
+    strong = 0
+    weak = 0
+    credit = 0.0
+    verb_counts: Counter[str] = Counter()
+
+    for b in bullets:
+        first = _first_word(b.text)
+        if b.has_action_verb:
+            strong += 1
+            credit += 1.0
+            verb_counts[first] += 1
+        elif first in _WEAK_STARTERS:
+            weak += 1
+        else:
+            credit += _NEUTRAL_VERB_CREDIT
+
+    overused = [v for v, n in verb_counts.items() if n >= 3]
+    penalty = min(15, 5 * len(overused))
+
+    score = max(0, min(100, round(credit / len(bullets) * 100) - penalty))
+
+    detail = f"{strong}/{len(bullets)} bullets start with a strong action verb."
+    if weak:
+        detail += f" {weak} weak starter(s) (worked/helped/used...)."
+    if overused:
+        detail += f" Overused: {', '.join(overused)} — vary your verbs."
+
+    return DimensionScore("action_verbs", score, detail, weight=1.0)
+
+
+# ---------------------------------------------------------------------------
+# 3. Quantification density
+# ---------------------------------------------------------------------------
+
+_NUMBER_RE = re.compile(
+    r"(?:\d[\d,]*(?:\.\d+)?\s*%|"
+    r"\d[\d,]*\+?\s+[\w/.-]+|"
+    r"sub-\d[\d.]*\s*(?:s|ms)|"
+    r"\$\d[\d,.]*[KMBkmb]?)"
+)
+
+
+_VAGUE_QUANTIFIERS = re.compile(
+    r"\b(?:several|many|various|numerous|multiple|significant(?:ly)?|"
+    r"a\s+(?:number|lot|variety)\s+of|some)\b",
+    re.IGNORECASE,
+)
+
+
+def _quantification_score(bullets: list[BulletScore]) -> DimensionScore:
+    if not bullets:
+        return DimensionScore("quantification", 0, "No bullets found.")
+
+    quantified = sum(1 for b in bullets if b.has_number)
+    ratio = quantified / len(bullets)
+    score = min(100, int(ratio * 110))
+
+    # Vague quantifiers in unquantified bullets are the cheapest wins —
+    # each "several" is a spot where a real number should live.
+    vague = sum(
+        1 for b in bullets if not b.has_number and _VAGUE_QUANTIFIERS.search(b.text)
+    )
+
+    detail = f"{quantified}/{len(bullets)} bullets contain measurable numbers."
+    if vague:
+        detail += (
+            f" {vague} bullet(s) use vague quantifiers (several/many/...)"
+            " — replace with real numbers."
+        )
+    if ratio < 0.4:
+        detail += " Aim for 50%+ quantified bullets."
+
+    return DimensionScore("quantification", score, detail, weight=1.5)
+
+
+# ---------------------------------------------------------------------------
+# 4. Section completeness
+# ---------------------------------------------------------------------------
+
+_EXPECTED_SECTIONS = {
+    "education": ["education"],
+    "experience": ["experience", "work", "internship", "employment"],
+    "projects": ["project"],
+    "skills": ["skill", "technical"],
+}
+
+_BONUS_SECTIONS = {
+    "certifications": ["certification", "certificate"],
+    "publications": ["publication", "paper", "research"],
+}
+
+
+def _section_completeness_score(resume: ParsedResume) -> DimensionScore:
+    section_names_lower = [s.name.lower() for s in resume.sections]
+
+    found_core = 0
+    missing_core: list[str] = []
+    for label, keywords in _EXPECTED_SECTIONS.items():
+        if any(kw in sn for sn in section_names_lower for kw in keywords):
+            found_core += 1
+        else:
+            missing_core.append(label)
+
+    total_core = len(_EXPECTED_SECTIONS)
+    bonus = 0
+    for keywords in _BONUS_SECTIONS.values():
+        if any(kw in sn for sn in section_names_lower for kw in keywords):
+            bonus += 1
+
+    base = (found_core / total_core) * 85
+    bonus_pts = min(15, bonus * 8)
+    score = min(100, int(base + bonus_pts))
+
+    detail = f"{found_core}/{total_core} core sections present."
+    if missing_core:
+        detail += f" Missing: {', '.join(missing_core)}."
+    if bonus:
+        detail += f" +{bonus} bonus section(s)."
+
+    return DimensionScore("section_completeness", score, detail, weight=0.75)
+
+
+# ---------------------------------------------------------------------------
+# 5. Brevity & formatting
+# ---------------------------------------------------------------------------
+
+
+def _brevity_score(bullets: list[BulletScore], resume: ParsedResume) -> DimensionScore:
+    if not bullets:
+        return DimensionScore("brevity", 50, "No bullets to evaluate.")
+
+    word_counts = [b.word_count for b in bullets]
+    avg_words = sum(word_counts) / len(word_counts)
+
+    too_long = sum(1 for wc in word_counts if wc > 35)
+    too_short = sum(1 for wc in word_counts if wc < 6)
+
+    total_bullets = len(bullets)
+    total_sections = len(resume.sections)
+
+    penalties = 0
+    if avg_words > 30:
+        penalties += 15
+    elif avg_words > 25:
+        penalties += 8
+    if too_long > total_bullets * 0.3:
+        penalties += 10
+    if too_short > total_bullets * 0.2:
+        penalties += 5
+    if total_sections < 3:
+        penalties += 10
+    if total_bullets > 25:
+        penalties += 5
+
+    score = max(0, min(100, 100 - penalties))
+
+    detail = f"Avg {avg_words:.0f} words/bullet across {total_bullets} bullets."
+    if too_long:
+        detail += f" {too_long} bullet(s) over 35 words."
+    if too_short:
+        detail += f" {too_short} bullet(s) under 6 words."
+
+    return DimensionScore("brevity", score, detail, weight=0.75)
+
+
+# ---------------------------------------------------------------------------
+# Bullet analysis
+# ---------------------------------------------------------------------------
+
+
+def _analyze_bullets(resume: ParsedResume) -> list[BulletScore]:
+    scores: list[BulletScore] = []
+
+    for sec in resume.sections:
+        for entry in sec.entries:
+            for bullet in entry.bullets:
+                text = bullet.text.strip()
+                words = text.split()
+                first_word = words[0].lower().rstrip(",.:;") if words else ""
+
+                has_verb = first_word in _STRONG_VERBS
+                has_num = bool(_NUMBER_RE.search(text))
+
+                scores.append(
+                    BulletScore(
+                        text=text,
+                        section=sec.name,
+                        has_action_verb=has_verb,
+                        has_number=has_num,
+                        word_count=len(words),
+                    )
+                )
+
+    return scores
+
+
+# ---------------------------------------------------------------------------
+# Resume text extraction
+# ---------------------------------------------------------------------------
+
+
+def _resume_plain_text(resume: ParsedResume) -> str:
+    parts: list[str] = []
+    for sec in resume.sections:
+        parts.append(sec.name)
+        for entry in sec.entries:
+            if entry.heading:
+                parts.append(entry.heading)
+            for b in entry.bullets:
+                parts.append(b.text)
+    return " ".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def score_resume(
+    resume: ParsedResume,
+    jd_text: str,
+) -> ATSScore:
+    """Score a parsed resume against a job description.
+
+    Returns an ATSScore with five dimensions (0–100 each) and a
+    weighted composite score.
+    """
+    bullet_scores = _analyze_bullets(resume)
+    resume_text = _resume_plain_text(resume)
+
+    dimensions = [
+        _keyword_match_score(jd_text, resume_text),
+        _action_verb_score(bullet_scores),
+        _quantification_score(bullet_scores),
+        _section_completeness_score(resume),
+        _brevity_score(bullet_scores, resume),
+    ]
+
+    total_weight = sum(d.weight for d in dimensions)
+    composite = (
+        sum(d.score * d.weight for d in dimensions) / total_weight
+        if total_weight
+        else 0
+    )
+
+    return ATSScore(
+        dimensions=dimensions,
+        bullet_scores=bullet_scores,
+        composite=round(composite, 1),
+        resume_name=resume.name,
+    )
+
+
+def score_tex_file(tex_path: Path, jd_text: str) -> ATSScore:
+    """Score a resume file (.tex, .pdf, or .txt) against a job description."""
+    from receipts.resume.loader import load_resume
+
+    resume = load_resume(tex_path)
+    return score_resume(resume, jd_text)
+
+
+def score_tex_string(tex_source: str, jd_text: str) -> ATSScore:
+    """Score a TeX string against a job description."""
+    resume = parse_resume(tex_source)
+    return score_resume(resume, jd_text)

receipts/ats/stats.py

@@ -0,0 +1,164 @@
+"""Statistical validation — confidence intervals on ATS score improvement.
+
+Uses bootstrap resampling (no scipy/numpy required). Provides confidence
+intervals and a simple significance test on per-bullet score deltas.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+from receipts.ats.scorer import ATSScore, BulletScore
+
+
+@dataclass(frozen=True)
+class ConfidenceInterval:
+    mean: float
+    lower: float
+    upper: float
+    confidence: float
+    n_samples: int
+
+
+@dataclass(frozen=True)
+class ImprovementReport:
+    keyword_match_ci: ConfidenceInterval | None
+    action_verbs_ci: ConfidenceInterval | None
+    quantification_ci: ConfidenceInterval | None
+    composite_delta: float
+    n_bullets_before: int
+    n_bullets_after: int
+    significant: bool
+
+    @property
+    def summary(self) -> str:
+        lines = [
+            f"Composite improvement: {self.composite_delta:+.1f} points",
+            f"Bullets: {self.n_bullets_before} → {self.n_bullets_after}",
+            f"Statistically significant: {'Yes' if self.significant else 'No'}",
+            "",
+        ]
+        for ci, name in [
+            (self.keyword_match_ci, "Keyword match"),
+            (self.action_verbs_ci, "Action verbs"),
+            (self.quantification_ci, "Quantification"),
+        ]:
+            if ci:
+                lines.append(
+                    f"  {name:<18} {ci.mean:+.1f} "
+                    f"[{ci.lower:+.1f}, {ci.upper:+.1f}] "
+                    f"({int(ci.confidence * 100)}% CI, n={ci.n_samples})"
+                )
+        return "\n".join(lines)
+
+
+def _bootstrap_ci(
+    values: list[float],
+    confidence: float = 0.95,
+    n_bootstrap: int = 1000,
+    seed: int = 42,
+) -> ConfidenceInterval:
+    """Compute bootstrap confidence interval for the mean of values."""
+    rng = random.Random(seed)
+    n = len(values)
+
+    if n == 0:
+        return ConfidenceInterval(
+            mean=0.0, lower=0.0, upper=0.0, confidence=confidence, n_samples=0
+        )
+
+    means: list[float] = []
+    for _ in range(n_bootstrap):
+        sample = [rng.choice(values) for _ in range(n)]
+        means.append(sum(sample) / n)
+
+    means.sort()
+    alpha = 1 - confidence
+    lower_idx = int((alpha / 2) * n_bootstrap)
+    upper_idx = int((1 - alpha / 2) * n_bootstrap) - 1
+
+    actual_mean = sum(values) / n
+
+    return ConfidenceInterval(
+        mean=round(actual_mean, 2),
+        lower=round(means[lower_idx], 2),
+        upper=round(means[upper_idx], 2),
+        confidence=confidence,
+        n_samples=n,
+    )
+
+
+def _bullet_metric_deltas(
+    before_bullets: list[BulletScore],
+    after_bullets: list[BulletScore],
+) -> dict[str, list[float]]:
+    """Compute per-bullet metric differences (paired where possible, then extras)."""
+    n = min(len(before_bullets), len(after_bullets))
+
+    verb_deltas: list[float] = []
+    quant_deltas: list[float] = []
+
+    for i in range(n):
+        verb_deltas.append(
+            float(after_bullets[i].has_action_verb)
+            - float(before_bullets[i].has_action_verb)
+        )
+        quant_deltas.append(
+            float(after_bullets[i].has_number) - float(before_bullets[i].has_number)
+        )
+
+    for i in range(n, len(after_bullets)):
+        verb_deltas.append(float(after_bullets[i].has_action_verb))
+        quant_deltas.append(float(after_bullets[i].has_number))
+
+    return {"action_verbs": verb_deltas, "quantification": quant_deltas}
+
+
+def compute_improvement(
+    before: ATSScore,
+    after: ATSScore,
+    confidence: float = 0.95,
+    n_bootstrap: int = 1000,
+) -> ImprovementReport:
+    """Compute statistical improvement report between two scores."""
+    composite_delta = after.composite - before.composite
+
+    kw_before = before.dimension("keyword_match")
+    kw_after = after.dimension("keyword_match")
+    keyword_ci = None
+    if kw_before and kw_after:
+        kw_delta = kw_after.score - kw_before.score
+        keyword_ci = ConfidenceInterval(
+            mean=float(kw_delta),
+            lower=float(kw_delta),
+            upper=float(kw_delta),
+            confidence=confidence,
+            n_samples=1,
+        )
+
+    deltas = _bullet_metric_deltas(before.bullet_scores, after.bullet_scores)
+
+    verb_ci = None
+    if deltas["action_verbs"]:
+        verb_ci = _bootstrap_ci(deltas["action_verbs"], confidence, n_bootstrap)
+
+    quant_ci = None
+    if deltas["quantification"]:
+        quant_ci = _bootstrap_ci(deltas["quantification"], confidence, n_bootstrap)
+
+    significant = composite_delta > 0 and (
+        (verb_ci is not None and verb_ci.lower > 0)
+        or (quant_ci is not None and quant_ci.lower > 0)
+        or composite_delta >= 5.0
+    )
+
+    return ImprovementReport(
+        keyword_match_ci=keyword_ci,
+        action_verbs_ci=verb_ci,
+        quantification_ci=quant_ci,
+        composite_delta=round(composite_delta, 1),
+        n_bullets_before=len(before.bullet_scores),
+        n_bullets_after=len(after.bullet_scores),
+        significant=significant,
+    )