feat: LLM keyword extraction via Calibrated Keyword Match Framework

V1 now uses an LLM call (Calibrated Keyword Match Framework) to identify
genuine hiring requirements before injection, replacing the run-gram
extractor that was pulling in people names, job board hashtags, company
marketing text, and LinkedIn UI noise from scraped JD pages.

- LLMClient.extract_keywords_llm(): sends JD to GLM with the framework
prompt; returns 15-25 ordered keyword strings (genuine skills, tools,
domain terms only); strictly excludes names, locations, UI noise
- optimize_latex_resume(): llm_client param; when provided, LLM keywords
replace the entire run-gram + quality-filter pipeline; falls back to
rule-based path if the LLM call fails
- latex_flow_for_api(): instantiates LLMClient and passes it through;
falls back gracefully if LLMClient construction fails

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

api_server.py

@@ -200,6 +200,7 @@ def latex_flow_for_api(
     """
     from src.latex_resume import optimize_latex_resume
     from src.candidate_vault import user_blocked_terms
+    from src.llm_client import LLMClient
 
     out_dir = tempfile.mkdtemp(prefix="latex_resume_")
     try:
@@ -207,6 +208,11 @@ def latex_flow_for_api(
     except Exception:
         blocked = []
 
+    try:
+        llm = LLMClient()
+    except Exception:
+        llm = None
+
     report = optimize_latex_resume(
         latex_src, jd_text,
         maximum_ats_mode=maximum_ats_mode,
@@ -216,6 +222,7 @@ def latex_flow_for_api(
         out_dir=out_dir,
         job_title=company or job_title or "resume",
         company=company or "",
+        llm_client=llm,
     )
     return report, out_dir
 

src/latex_resume.py

@@ -827,6 +827,7 @@ def optimize_latex_resume(
     job_title: str = "",
     company: str = "",
     progress_callback=None,
+    llm_client=None,
 ) -> Dict:
     """End-to-end LaTeX flow: gate → inject → (compile) → measure coverage.
 
@@ -846,44 +847,57 @@ def optimize_latex_resume(
     base_text = latex_to_text(latex_src)
 
     _prog("Analyzing job description…", 10)
-    decision = decide_includable_terms(
-        jd_text, base_text,
-        maximum_ats_mode=maximum_ats_mode,
-        confirmed_terms=confirmed_terms,
-        pasted_terms=pasted_terms,
-        blocked_terms=blocked_terms,
-    )
-    expected = decision["expected_terms"]
-    # V1 noise fix: strip LinkedIn UI / metadata noise from the keyword pool
-    includable = filter_scraped_noise(decision["includable"], jd_text, company)
-
-    # V1 ATS quality filter — three-tier trust model:
-    #   Tier 1: taxonomy floor + curated vocab → always trusted, no frequency gate
-    #   Tier 2: 2-word JD phrases → keep (any freq; specific enough)
-    #   Tier 3: 3-word JD phrases → only if freq >= 2 in JD (else likely a sentence fragment)
-    #   Drop:   4+ word phrases (almost always run-on fragments from comma-separated lists)
-    from .external_ats import extract_jd_keywords as _tax_fn
-    try:
-        from config import MAXIMUM_ATS_SAFE_TERMS as _SAFE
-    except Exception:
-        _SAFE = set()
-    _jd_low = jd_text.lower()
-    _trusted = set(_tax_fn(jd_text)) | {t for t in _SAFE if t in _jd_low}
-    def _keep(t):
-        if t in _trusted:
-            return True
-        words = t.split()
-        nw = len(words)
-        if nw >= 4:
-            return False
-        freq = len(re.findall(r'\b' + re.escape(t) + r'\b', _jd_low))
-        if nw == 1:
-            return freq >= 1        # any occurrence; filler/stop already stripped upstream
-        if nw == 2:
+
+    if llm_client is not None:
+        # LLM path: Calibrated Keyword Match Framework extracts only genuine hiring
+        # requirements — no LinkedIn UI noise, people names, or company marketing.
+        _prog("Identifying keywords with AI…", 20)
+        llm_kws = llm_client.extract_keywords_llm(jd_text)
+        if llm_kws:
+            base_low = base_text.lower()
+            # Skip terms already present in the resume (word-boundary aware).
+            includable = [t for t in llm_kws if not _term_present(t.lower(), base_low)]
+            expected = [t.lower() for t in llm_kws]
+            _trusted = {t.lower() for t in llm_kws}
+            gated = {}
+        else:
+            # LLM call failed — fall through to the rule-based path below.
+            llm_client = None
+
+    if llm_client is None:
+        # Rule-based fallback (original run-gram extraction + quality filter).
+        decision = decide_includable_terms(
+            jd_text, base_text,
+            maximum_ats_mode=maximum_ats_mode,
+            confirmed_terms=confirmed_terms,
+            pasted_terms=pasted_terms,
+            blocked_terms=blocked_terms,
+        )
+        expected = decision["expected_terms"]
+        includable = filter_scraped_noise(decision["includable"], jd_text, company)
+
+        from .external_ats import extract_jd_keywords as _tax_fn
+        try:
+            from config import MAXIMUM_ATS_SAFE_TERMS as _SAFE
+        except Exception:
+            _SAFE = set()
+        _jd_low = jd_text.lower()
+        _trusted = set(_tax_fn(jd_text)) | {t for t in _SAFE if t in _jd_low}
+        def _keep(t):
+            if t in _trusted:
+                return True
+            words = t.split()
+            nw = len(words)
+            if nw >= 4:
+                return False
+            freq = len(re.findall(r'\b' + re.escape(t) + r'\b', _jd_low))
+            if nw == 1:
+                return freq >= 1
+            if nw == 2:
+                return freq >= 1
             return freq >= 1
-        return freq >= 1            # 3-word: any occurrence qualifies
-    includable = [t for t in includable if _keep(t)]
-    gated = decision["gated"]
+        includable = [t for t in includable if _keep(t)]
+        gated = decision["gated"]
 
     _prog("Placing keywords in resume…", 45)
     final_src, injected = inject_keywords(latex_src, includable, trusted_set=_trusted)

src/llm_client.py

@@ -66,6 +66,65 @@ class LLMClient:
                             break
         raise ValueError(f"Cannot parse JSON: {text[:200]}")
 
+    # ──────────────────────────────────────────────────────────
+    # KEYWORD EXTRACTION — Calibrated Keyword Match Framework
+    # ──────────────────────────────────────────────────────────
+    def extract_keywords_llm(self, jd_text: str) -> list[str]:
+        """Extract ATS keywords from a JD using the Calibrated Keyword Match Framework.
+
+        Returns a list of 15-25 keyword strings ordered from highest to lowest ATS
+        priority. Returns [] on any failure so the caller can fall back gracefully.
+        """
+        system = (
+            "You are an ATS-aligned Job Description Keyword Intelligence Engine.\n\n"
+            "Identify the SMALLEST, HIGHEST-VALUE set of keywords that represent the "
+            "employer's actual hiring criteria for ATS platforms like Greenhouse.\n\n"
+            "INCLUDE ONLY:\n"
+            "- Specific skills, methodologies, and competencies (e.g. 'product strategy', "
+            "'A/B testing', 'roadmap prioritization')\n"
+            "- Named tools and technologies (e.g. 'SQL', 'Jira', 'Mixpanel', 'Salesforce')\n"
+            "- Domain/industry terms (e.g. 'e-commerce', 'B2C', 'SaaS', 'quick-commerce')\n"
+            "- Specific role competencies stated in the JD (e.g. 'stakeholder management', "
+            "'cross-functional leadership')\n"
+            "- Experience signals stated as requirements (e.g. '5+ years product management')\n\n"
+            "EXCLUDE STRICTLY — these must NEVER appear in the output:\n"
+            "- Company names, brand names, product names of the hiring company\n"
+            "- People names (recruiters, employees, executives listed anywhere on the page)\n"
+            "- City/country/location names\n"
+            "- Job board tags, hashtags, recruitment platform UI text (e.g. 'easy apply', "
+            "'search faster', 'trial ends', 'followers', career fair text)\n"
+            "- Generic personality adjectives ('passionate', 'dynamic', 'results-driven')\n"
+            "- Benefits, compensation, equal-opportunity, or marketing language\n"
+            "- Random words with no skill meaning\n"
+            "- Duplicate variations of the same concept\n\n"
+            "PRIORITY ORDER:\n"
+            "1. Terms marked required/must-have\n"
+            "2. Terms in the job title or opening summary\n"
+            "3. Specific skills/tools repeated across the JD\n"
+            "4. Domain expertise terms\n"
+            "5. Preferred/nice-to-have terms\n\n"
+            "Return ONLY a JSON array of 15-25 keyword strings, ordered highest to lowest "
+            "ATS priority. No markdown fences, no explanation, just the array.\n"
+            'Example: ["product strategy","stakeholder management","A/B testing","SQL",'
+            '"roadmap prioritization","OKRs","go-to-market","data analytics"]'
+        )
+        user = f"Job Description:\n{(jd_text or '')[:4000]}"
+        try:
+            raw = self._call(system, user, max_tokens=512)
+            data = self._extract_json(raw)
+            if isinstance(data, list):
+                return [str(k).strip() for k in data
+                        if k and len(str(k).strip()) >= 3][:30]
+            if isinstance(data, dict):
+                out: list[str] = []
+                for v in data.values():
+                    if isinstance(v, list):
+                        out.extend(str(k).strip() for k in v if k and len(str(k).strip()) >= 3)
+                return out[:30]
+        except Exception as e:
+            print(f"[extract_keywords_llm] failed: {e}")
+        return []
+
     # ──────────────────────────────────────────────────────────
     # BATCH ASSESSMENT — sends 8 jobs per API call (8× faster)
     # ──────────────────────────────────────────────────────────