Hugging Face's logo

Spaces:
saitejatirunagari
/
JAA-ATS-Tool
Running

App Files Community
JAA-ATS-Tool / README.md
saitejatirunagari's picture
saitejatirunagari
feat: natural keyword sentence placement across resume sections
8c3cb9e
preview code
|
Raw
History Blame Contribute Delete
35.4 kB
metadata 
title: JAA ATS Tool
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: mit

Job Automation Agent — PM Edition

Automated Product Manager job search, AI-powered assessment, ATS-optimized resume generation, and Google Sheets reporting — all in one pipeline.

What It Does

Step What Happens
1 Parses your PDF resume (Kimi-K2.6, ~5s)
2 Scrapes PM-only jobs from LinkedIn, Indeed, Glassdoor, Remotive, WeWorkRemotely — ALL selected roles × locations, last N days
3 Filters non-PM roles at scrape time; dedup by URL + (title, company) + 30-day SQLite history; platform-level total cap
4 Fetches FULL job descriptions in bulk (parallel HTTP / single browser session)
5 Assesses ALL jobs using 7 parallel AI models (10-model pool via NVIDIA API)
6 Generates ATS-optimized resumes for ALL jobs — DOCX and PDF, After ≥ Before guaranteed, target 95%
7 Writes everything to your Google Sheet with direct job links
8 Saves local Excel report + resumes in data/output/resumes/YYYY-MM-DD/
9 Saves run to history — reload past runs in one click from the History panel

Quick Start 

# 1. Install dependencies
pip install -r requirements.txt
playwright install chromium

# 2. Copy and fill in your API keys
copy .env.example .env
# Edit .env with your NVIDIA_API_KEY, GOOGLE_SHEET_ID, etc.

# 3. Place your resume PDF
# Copy your resume to: data/resume/resume.pdf

# 4. Connect Google (one-time browser login)
python connect_google.py

# 5. Run a test (5 jobs)
# In config.py: ASSESSMENT["test_mode"] = True
python main.py

# 6. Run full production mode (all 100+ PM jobs)
# In config.py: ASSESSMENT["test_mode"] = False
python main.py

# 7. Or use the Streamlit UI
streamlit run ui.py

ever-jobs Integration (160+ Platforms)

This project integrates the ever-jobs NestJS service, which provides REST API access to 160+ job board scrapers.

Prerequisites

Setup (one-time) 

# Clone ever-jobs to vendor/ directory (done automatically during setup)
git clone https://github.com/ever-jobs/ever-jobs.git vendor/ever-jobs --depth=1

# Start via Docker (preferred)
cd vendor/ever-jobs && docker compose up -d

# Verify API is running
curl http://localhost:3001/health
# OR from Python:
python -c "from src.ever_jobs_bridge.server import is_running; print(is_running())"

Automatic Startup

The pipeline calls ensure_running() automatically before any ever-jobs platforms are scraped. It tries Docker first, falls back to npm run start if Docker is unavailable.

Platform Selection

The UI has a single "🌐 Job Platforms" section with three groups. Selecting LinkedIn, Indeed, Glassdoor, Remotive, WeWorkRemotely, or Naukri uses their dedicated high-quality scrapers; all other platforms go through the ever-jobs REST API.

Group Count Description
Search Boards 94 General job boards. India-relevant defaults pre-selected.
ATS Platforms 37 Greenhouse, Lever, Workday etc. — companies post jobs here. NOT resume scoring.
Company Pages 39 Direct career pages (Flipkart, Swiggy, Amazon, Google, etc.)

India default platforms: linkedin, naukri, indeed, glassdoor, google, bdjobs, internshala, bayt, iimjobs, foundit

ATS Clarification

Important: "ATS" in ever-jobs means Applicant Tracking System PLATFORMS (tools companies use to post jobs, like Greenhouse or Lever). It does NOT mean ATS resume scoring.

Our ATS resume scoring (src/ats_scorer.py) uses a 70% JD keyword match + 30% resume quality hybrid and is NOT changed by this integration.

Performance Notes

Selection Expected Time
Default 10 platforms ~1–3 minutes
30 platforms ~3–5 minutes
100+ platforms 5–10 minutes (warning shown in UI)

Playwright-based scrapers (some company pages) are inherently slower than API-based boards.

Cross-Platform Deduplication

In addition to URL-based dedup, a content fingerprint (SHA-256 of normalized title+company) catches cross-platform duplicates. For example, the same "Product Manager at Google" posting on LinkedIn AND Greenhouse (different URLs) is detected and deduplicated.

Project Structure 

Job Automation Agent/
├── main.py                    # Main pipeline (6-step orchestrator)
├── config.py                  # All configuration — models, platforms, ATS settings
├── ui.py                      # Streamlit UI (4 tabs: Search, Results, Job Details, Research)
├── connect_google.py          # One-time Google OAuth setup
├── setup_google.py            # Service account alternative
├── requirements.txt
├── .env                       # API keys (never commit)
├── .env.example               # Template for .env
│
├── src/
│   ├── resume_parser.py       # PDF → plain text (pdfplumber)
│   ├── llm_client.py          # GLM 5.1 wrapper (profile extract, resume customize)
│   ├── model_pool.py          # 10-model parallel AI pool (NVIDIA API)
│   ├── job_assessor.py        # Phase 1 keyword scoring + Phase 2 LLM assessment
│   ├── job_history.py         # SQLite dedup store (data/job_history.db)
│   ├── ats_scorer.py          # Hybrid ATS scoring (70% JD match + 30% quality)
│   ├── resume_customizer.py   # LLM-tailored DOCX resume generator
│   ├── gsheets.py             # Google Sheets + Drive upload
│   ├── excel_reporter.py      # Local Excel report
│   ├── odysseus_llm_core.py   # Deep research LLM core
│   │
│   ├── ever_jobs_bridge/       # ever-jobs NestJS REST API adapter
│   │   ├── __init__.py        # Package init
│   │   ├── server.py          # Docker/npm server lifecycle (start/stop/health)
│   │   ├── client.py          # HTTP client for POST /api/jobs/search
│   │   ├── mapper.py          # IJob JSON → Job dataclass mapper
│   │   └── platforms.py       # 170 platform catalog with group metadata
│   │
│   ├── scrapers/
│   │   ├── base.py            # Job dataclass + BaseScraper + is_pm_role() filter
│   │   ├── linkedin.py        # LinkedIn scraper (requests + BeautifulSoup)
│   │   ├── indeed.py          # Indeed scraper (Playwright for JS rendering)
│   │   ├── glassdoor.py       # Glassdoor scraper (Playwright)
│   │   ├── naukri.py          # Naukri (disabled — blocked by Akamai)
│   │   └── ever_jobs.py       # EverJobsScraper (REST adapter for 160+ platforms)
│   │
│   └── research/
│       ├── deep_researcher.py # Odysseus IterResearch engine (Think→Search→Extract→Synthesize)
│       └── search.py          # DuckDuckGo + Bing fallback, 12h cache
│
└── data/
    ├── resume/resume.pdf      # Your resume (add this)
    ├── job_history.db         # Dedup SQLite DB (auto-created)
    ├── research_cache/        # 12h DuckDuckGo result cache
    └── output/
        ├── resumes/           # Generated DOCX resumes (Company_JobTitle.docx)
        └── reports/           # Excel reports

Configuration (config.py)

AI Models (10-model pool via NVIDIA API)

Model Speed Phase 2 Notes
Kimi-K2.6 ~5s/batch ✅ Fastest, handles most work
Step-3.7-Flash ~8-35s ✅
Qwen3.5-397b ~9s ✅
Qwen3.5-122b-v2 ~12s ✅
GPT-OSS-120b ~11s ✅
Qwen3.5-122b ~40s ✅
DeepSeek-v4-Pro ~42s ✅
DeepSeek-v4-Flash ~229s ❌ Too slow for phase 2
GLM-5.1 ~234s ❌ Used for resume parsing only
MiniMax-M2.7 ~908s ❌ Blocked/rate-limited

Key Settings 

ASSESSMENT = {
    "min_score_for_llm_resume": 6,   # LLM-tailored resume for score >= this
    "generate_all_resumes":     True, # Template resume for ALL PM jobs
    "max_llm_resumes":          30,   # Max LLM resumes per run
    "dedup_days":               30,   # Skip jobs seen in last 30 days
    "test_mode":                True, # ← Set False for full production run
    "test_jobs_limit":          5,    # Max jobs in test mode
}

ATS Scoring Method

Natural keyword sentence placement

When remaining JD keywords are not covered by the V1 evidence-gated rewriter, place_keywords_naturally() distributes them as natural PM resume sentences across project, experience, and skills sections. Each sentence packs 8-10 keywords into a single 20-25 word bullet using semantic role categorization (primary/context/method/outcome). Keywords are inserted bottom-to-top in the LaTeX to prevent offset corruption. Credentials, education, licences, and seniority requirements are never placed this way.

Hybrid scoring: 70% JD Match + 30% Resume Quality

  • JD Match (70%): Extract keywords FROM the specific job description → match against resume using word-boundary regex ((?<!\w)kw(?!\w)) — same approach as Resume-Matcher
  • Resume Quality (30%): 6-factor structural analysis (measurable achievements, contact info, education, etc.)
  • Iterative optimization: Up to 3 LLM attempts to push score up, gap report fed back each iteration
  • Fallback: _inject_missing_keywords() weaves still-missing terms naturally

Keyword extraction is JD-driven, skills-only, and honest (industry standard)

  • Keywords are extracted from each JD itself (not a fixed stored list), but skills-only: a term is kept only if it's a recognised skill/tool/method/ domain/soft-skill in our gazetteer. Prose nouns (Goals, Authority, Enterprise, Productivity…) can never become "keywords" — exactly how real checkers like Jobalytics work (they match against a curated skills list, not every word).
  • Dedicated, categorized SKILLS section (Tools & Analytics / Methodologies / Domains / Core Competencies) — the #1 ATS keyword vehicle, placed after the summary, parsed and counted by Jobalytics/Resume Worded.
  • Quality over quantity: cover the JD's real skills (~20–26), each 1–3×, across the skills section + summary + woven bullets. Best practice is 15–25 keywords at 60–80% coverage — NOT 100 stuffed terms.
  • No cap, distributed smartly. Every meaningful missing keyword is kept — woven into relevant bullets first (the ideal, never-penalised place), then any remainder spread across several short sentences (each its own paragraph, ≤10 items). A single long comma-dump is deliberately not produced: _strip_keyword_spam removes any 15+-separator line before scoring, exactly as real ATS checkers and recruiters discount stuffing — so distributing keeps them all counted without looking like spam.
  • Buzzwords removed. Vague abstractions (innovation, solutions, tools, leadership, leverage, scalable…) are never injected — real checkers like Resume Worded penalise them.
  • Honest expectation: 90%+ is reached on JDs that genuinely fit the candidate's background. Out-of-domain JDs score honestly lower — that reflects reality (and matches third-party checkers), rather than a faked number.
  • The displayed score is a conservative estimate (leans low vs our raw internal coverage); always verify the final resume on Jobalytics/Simplify.

Benchmark results (correctly differentiates — full resume + capable LLM):

  • In-domain PM JDs (Airtel, generic PM) → ~83–87
  • Out-of-domain JDs (SecOps, lending) → ~60–70, honestly

Telegram Bot (mobile touchpoint, via Cloudflare relay)

Third touchpoint alongside the Streamlit app and Chrome extension: send a job link (or paste the JD) to your Telegram bot and get back a tailored resume PDF.

Architecture note: HF Spaces block outbound traffic to api.telegram.org, so the HF app can receive webhooks but can't send replies. The bot therefore runs through a tiny Cloudflare Worker relay (free, always-on, can reach Telegram): Telegram → Worker → HF /api/generate (does JD-fetch + tailoring + Tectonic compile) → Worker sends the PDF back. Worker code + full setup: relay/cloudflare-worker.js and relay/README.md.

/api/generate accepts jd_url (server fetches/extracts the JD) or jd_text, and falls back to the bundled default resume when no resume is supplied — so the relay stays a thin Telegram-I/O layer.

(The legacy in-Space POST /telegram/webhook + GET /telegram/diag remain for diagnostics, but the working path is the Cloudflare relay because of the egress block.)

Chrome Extension + JSON API

Apply one job at a time in the browser (no bulk scraping → no IP-blocking). The HF Space serves BOTH the Streamlit app and a JSON API from one codebase — so the score is identical to the web app (proven by tests/test_api_parity.py).

Setup: load extension/ unpacked → Options → paste your resume LaTeX (or upload a PDF) + set API URL (https://<your-space>.hf.space) + API_SECRET_TOKEN. Then open any job → Run → tailored resume download.

Resume LaTeX (recommended): paste your resume's LaTeX source in Options. When present it is prioritised over the PDF — we extract its text for keyword matching, inject the honestly-includable JD keywords distributed across a Summary sentence, Experience bullets, and one compact competencies line (never a dump), and compile it to a clean PDF (Tectonic on the Space) you download directly (plus the modified .tex). This fixes the generated-PDF design issues because the layout is your own LaTeX. Anti-faking is identical: certs, seniority, employers, and specialised hands-on engineering terms are never injected. Verify: python scripts/verify_latex_resume.py.

Recruiter-grade placement + resilient Run (Phase 7, v1.4.0): JD extraction now strips page/extension UI chrome (Simplify/Jobalytics overlays) so junk like "Show Match Details" / "People Clicked Apply" never becomes a keyword; the DOCX Skills section is one capped line per category (18-28 items, no repeated "Core Competencies:" dumps) with surplus keywords woven into Summary + Experience; and clicking Run now survives the popup closing — the background owns the run and the popup restores the spinner/result on reopen. Verify: python scripts/verify_clean_jd_extraction.py, verify_skills_distribution.py, verify_resilient_run.py.

Trust + usability (Phase 8, v1.5.0):

  • Download a real PDF, not just DOCX. The DOCX path now always renders a PDF sidecar (reportlab on Linux/HF) so the PDF button works even without LaTeX; the LaTeX path compiles a clean PDF via Tectonic and, if compilation fails, tells you why (no engine vs LaTeX error) while still offering the .tex.
  • Your resume is preserved — non-destructive tailoring is the default. Role titles, companies, dates, and your existing bullets are kept VERBATIM; keywords are added only in the Professional Summary and as ≤3 appended lines at the end of each experience. Nothing you wrote is renamed or rewritten.
  • Persistent left side panel (Jobalytics-style). The UI is now a collapsible panel docked to the left of the page instead of a popup that vanishes — click Run, then click anywhere on the page; the run keeps going and stays visible.
  • History. A History list in the panel shows your previous generations per job (title/company/time/scores/status); click any entry to restore it and re-download DOCX/PDF/.tex. Verify: python scripts/verify_pdf_download.py, verify_non_destructive.py, verify_side_panel.py, verify_history.py.

API endpoints (api_server.py, port 7860, X-Api-Token header):

  • GET /api/health → {status: ok}
  • POST /api/generate — multipart jd_text + (resume_latex or resume PDF; LaTeX wins) → tailored resume. PDF path returns base64 DOCX/PDF; LaTeX path returns compiled pdf_b64 + tex_b64 + external coverage report.
  • POST /api/repair-with-feedback — External ATS Feedback Repair Mode: paste Jobalytics/Simplify feedback (score + missing keywords); every missing keyword is risk-classified by candidate_fit and woven honestly into bullets/skills (or injected into your LaTeX when resume_latex is supplied).

Feedback-repair honesty rules (never relaxed):

  • LOW → auto-weave; MEDIUM → auto-weave + review flag; HIGH → not added, returned as "needs your confirmation"; BLOCKED → excluded. No fake skills/seniority/employers/degrees/certs.
  • Scores come from the re-parsed exported file; READY needs internal AND independent ≥ 90 AND ATS readability ≥ 90 AND parse validation.

Statuses: READY_95_EXTERNAL_ALIGNED (≥90 both + pasted gaps mostly resolved) · READY_90_PLUS_REVIEW_RECOMMENDED (medium-risk added) · NEEDS_USER_INPUT (95 needs high-risk terms you must confirm) · NOT_ELIGIBLE_LOW_FIT (can't reach 90/95 without fabrication).

Verify: PYTHONPATH=. python scripts/verify_feedback_repair.py (deterministic; proves blocked/high terms never enter the resume).

Maximum ATS Mode (User-Confirmed Skill Expansion)

For your target role family (Product / Product Manager / AI Product Manager / SaaS / B2B), the uploaded resume is treated as an incomplete base profile. Enable Maximum ATS Mode (extension toggle, on by default; API field maximum_ats_mode=1) to treat normal PM/Product/AI/agile vocabulary — AI, ML, generative AI, prompt design, model evaluation, QA, experimentation, data-driven, analytics, roadmap, product strategy, product ownership, agile, scrum, user stories, acceptance criteria, PRD, stakeholder management, SaaS, B2B, enterprise platform, product discovery, go-to-market, retention, growth, etc. — as user-confirmed / interview-supportable and aggressively place them across Summary, Skills, Key Achievements and Experience. It targets 95 external ATS and treats anything below 90 for in-family roles as a failure state to keep repairing (unless the only gaps are genuinely blocked).

Still never fabricated (hard boundaries, unchanged): degrees, certifications/ licenses, employers, titles, years/seniority, regulated credentials, and specialized hands-on engineering/security tools (those surface as "needs your confirmation", with a one-click Confirm & regenerate).

For the extension's Generate Application flow, the resume owner has opted in to this confirmed-skill expansion. Every professional JD skill that is not already in the base resume is placed in a Confirmed Skills section as short, role-relevant sentences instead of a keyword list. This applies only to skills; the factual boundaries above remain excluded. External ATS scores cannot be guaranteed, but all includable JD skills are physically present in the export.

  • Both endpoints accept maximum_ats_mode / user_confirmed_expansion, confirmed_terms, target_external_score (default 95). Backward compatible.
  • Responses include a rich coverage report (per keyword: category, risk, disposition, the resume section it was placed in, and why anything was excluded), still_missing_repairable, and a plain-English below_target_explanation.
  • Confirmed expansion terms persist to the Candidate Vault (user_confirmed) so future resumes treat them as safe.

Maximum-ATS statuses: READY_MAX_ATS_95_PLUS (gates pass + external coverage ≥ 95) · READY_90_PLUS_EXTERNAL_ALIGNED (gates pass + coverage ≥ 90) · BELOW_TARGET_REPAIRABLE (below target, remaining gaps LOW/MEDIUM → keep repairing) · NEEDS_USER_CONFIRMATION (only high-risk-but-supportable terms left).

External-coverage is the success signal (not the internal score). Our internal scorer uses a narrow taxonomy (→ 90%+ easily); external checkers extract a broad 40-46 term set (→ can be ~54% on the same resume). So in Maximum ATS Mode the system builds a broad Jobalytics-style expected set (src/external_ats.py), physically guarantees every includable term into the exported DOCX (Skills verbatim + woven into Experience bullets; HIGH/BLOCKED stay gated), re-parses the file, and measures coverage from the export. Status is then READY_MAX_ATS_95_PLUS (≥95) / READY_90_PLUS_EXTERNAL_ALIGNED (≥90) / BELOW_TARGET_REPAIRABLE — an internal-96 / external-54 result is treated as a bug, never "done". Both endpoints return external_coverage + a per-term coverage_report (keyword / found in export / section / why-missing) and log maximum_ats_mode.

Verify (deterministic, no keys):

  • PYTHONPATH=. python scripts/verify_maximum_ats.py — PM/AI terms become user-confirmed; certs/seniority/engineering stay gated; coverage improves.
  • PYTHONPATH=. python scripts/verify_max_ats_coverage.py — the 26/46 live-failure regression: exported DOCX covers ≥90% of includable PM terms; credentials/fake seniority excluded; status driven by external coverage.

Generation Modes (V1 / V2)

Two resume tailoring modes, selectable per surface:

V1 — Structured Keyword Placement (default)

Evidence-gated extraction + natural sentence placement into the hardcoded resume. The V1 rewriter aligns existing bullets to JD terminology, then place_keywords_naturally() distributes remaining keywords as 20-25 word natural sentences across project and experience sections (8-10 keywords per bullet, bottom-to-top insertion). Overflow keywords go to categorized Skills lines. Fast (no LLM call for placement); keywords appear as genuine resume content, not comma-separated dumps.

Before/after score symmetry (required invariant). The V1 alignment estimate reports a before and an after score, and the delta is the headline number the extension shows. Anything that reaches only one of those two calls becomes a fake delta. Three such leaks were fixed on 2026-08-05 after the extension reported a decrease (66 → 41) with zero content change:

  • Never score per-line. before_text comes from latex_to_text while score_text comes from the extracted PDF, and those wrap lines differently. The old per-line _detect_stuffing therefore measured the same résumé at 25.0 unwrapped and 0.0 wrapped — a 25-point swing of pure rendering artifact (66 - 25 = 41). Any new text heuristic must be whitespace-normalized first.
  • pdf_validation goes to both sides or neither. It was passed only to the AFTER score, making parseability a one-sided penalty worth up to 20 points against the tailored résumé. score_before is now computed after the compile so it receives the same value and parseability cancels from the delta.
  • A Skills section is formatting, not stuffing. The old ">=6 commas on a line" rule flagged every real résumé's Skills block and cost a correctly formatted document 15-25 points. The rule now needs >=6 consecutive single-word tokens, which separates a bare dump (Kubernetes, Docker, Go, Rust, …) from multi-word competencies (Roadmap Planning, Feature Prioritization, …).

Calibration is evidence-aware. calibrate() distributes a 100-point weight budget across 4-6 match-critical criteria. Because the pipeline never fabricates, weight spent on an unsupported criterion can never be earned — it only lowers the reachable ceiling. It previously ranked on JD-side priority alone and routinely gave half the budget to gaps, which is why runs reported supported phrases added (0) and the score could not move. It now takes supported_concepts (from the evidence gate, mapped before calibration) and ranks evidence-backed criteria ahead of gaps of equal JD priority. Gaps are still fully reported — just not weighted. Measured end-to-end: 56 → 56 (flat) became 59 → 71 (+12).

tests/test_score_symmetry.py locks all four invariants. When touching the scorer, run it — a flat or negative delta on an unchanged résumé is a defect, not a result.

V2 — Multi-Agent Natural Integration

V2 is a multi-agent pipeline, not keyword-filling:

  1. Rank — after extraction, every model in the fast pool (Kimi-K2.6, Qwen3.5-397b, GPT-OSS-120b, Step-3.7-Flash) scores each keyword 0–100 for its potential/relevance to the role. Scores are averaged into a consensus ranking and the low-relevance tail is dropped (V2_RANK_MIN_SCORE, default 40; floor V2_RANK_FLOOR, default 15). The top-ranked keywords flow into the most prominent sections (summary first).
  2. Fan-out — every pool model independently rewrites the résumé, weaving the top-ranked keywords into natural, recruiter-credible bullets.
  3. Judge — Kimi scores all candidates and picks the one that reads most naturally while covering the most top keywords.
  4. Refine — Kimi runs one more pass on the winner to remove any residual stuffing, ensure a single cohesive summary, and keep every claim honest.

(judge_note in the API response shows the path, e.g. ranked:4agents+fan_out:4models+refined.)

Atomic coverage scoring (R32). V2 scores keyword coverage against atomic keywords, not multi-word run-grams: a JD list like "SaaS, cloud, AWS, Azure" is decomposed into individual terms before matching (real ATS checkers score individual keywords, not exact 4-word phrases), while genuine multi-word skills (go-to-market, machine learning, product roadmap) are preserved. This removes a large false-negative deflation (a well-fit Porter PM résumé: +21pt on the same keyword set). A coverage-aware weave pass then closes the remaining claimable gap with one targeted call, and feed/collections URLs are truncated to a single job before extraction. Scoring stays calibrated to real checkers (validated against the Experian fixture). Note: keyword coverage is one signal for recruiter search discoverability, not an auto-reject gate (most ATS organize for human review rather than score-and-reject).

Honest 90%+ scoring (R33). The V2 scoring denominator drops prose-noise via skill_relevant_filter (a blocklist — an allowlist would self-grade) and doubles acronym forms via _expand_acronyms (AWS ↔ Amazon Web Services) for recruiter search. A weave-to-target loop (up to V2_WEAVE_MAX_PASSES, default 3) then weaves only claimable missing skills naturally until coverage clears 90% on a genuinely-fit role — never fabricating, honesty-reverting each pass. Scoring stays calibrated to real checkers (the Experian fixture holds at ~60%, Jobalytics ±10). A parseability verifier (src/parseability.py) reports structural ATS issues (section headers, contact info, text-extractability, column layout) on every generated résumé. All V2-only; V1 unchanged.

Key properties:

  • No keyword filling. The verbatim-every-keyword rule is gone; if a keyword can't be woven naturally it's dropped. There is no comma-dump fallback — a section with no natural sentence gets nothing.
  • Summary is merged, not appended. V2 rewrites the existing summary into one paragraph (no duplicate "5+ years" opening).
  • Skills "Other" is a short, curated list of genuine tools only — never a raw keyword dump.
  • Honesty boundaries preserved. Falls back to single-model, then V1 placement, if the whole pool fails. ~30–60s single résumé; capped/parallelized for bulk.

Scraped-noise filter (V2-only). Before allocation, V2 passes the keyword pool through filter_scraped_noise() (src/external_ats.py), which drops tokens a raw JD scrape drags in but that are never resume keywords: company geography (Amsterdam, Latin America…), the hiring company's own name, executive/recruiter and other person names (cue-gated, e.g. "Recruiter: …" / "… is the CEO"), corporate-entity/boilerplate nouns (corporation, members, backbasers…), and job-board page chrome ("actively engaged", "easy apply"…). Genuine skill/tool/ domain keywords (REST, SOAP, GraphQL, iPaaS, reconciliation, Agile, banking integrations…) are preserved. V1 placement is intentionally NOT filtered — this is scoped to V2 only.

PM Keyword Placer Skill (V3 Corpus)

A reusable keyword assignment rule set derived from 39 real PM JDs (AI/GenAI PM, SaaS/Platform, Growth/B2C archetypes; India-market weighted). Installed at ~/.claude/skills/pm-keyword-placer/SKILL.md.

Purpose: Given keywords extracted from a specific JD, the skill returns the correct placement for each — which Skills category, which Experience bullet, or "already present" — so the V2 pipeline weaves them into the right place without guessing. Rules are derived from corpus frequency (how many of the 39 JDs contain each keyword) and confirmed by the user.

Key properties:

  • Operates on the current JD's keywords only — does not dump all 129 corpus keywords into every resume.
  • Keywords go into sentences (V2 natural weaving), never comma-dumped.
  • 32 already-present rules prevent redundant additions.
  • 3 explicit skip rules (red teaming, GRC, RICE/ICE) prevent out-of-domain fabrication.
  • Extensible: any new JD keyword not in the 129 rules triggers an assign+draft flow — user picks the section once, I draft the statement, rule is added permanently.

Coverage (129 rules): skills.ai (25) · skills.growth (19) · skills.product (21) · skills.acq (10) · skills.tools (19) · experience bullet targets with statement templates (20) · already-present (32) · skip (3).

Automatic (V2 pipeline): src/keyword_placer.py runs as step 1d in generate_v2 — after keyword allocation, before fan-out. The placement brief is injected into every fan-out model's prompt automatically, so the extension, bot, and HF Space all benefit with zero configuration.

Manual (Claude Code skill): paste a JD and use /pm-keyword-placer to get the placement plan interactively before a V2 generation pass.

Selecting a version

Surface How to choose
/api/generate version=v1 or version=v2 form field; default from GEN_VERSION_DEFAULT env (v2)
HF Streamlit V1/V2 radio on the home page; bulk pipeline honors the selection
Chrome extension Default in Options (gen_version_default) + per-run toggle in the popup
Telegram bot /v1, /v2 commands set per-user default; /mode shows current

Env knobs

Variable Default Description
GEN_VERSION_DEFAULT v2 Default version when not specified (V2 is now the default across HF, extension, and Telegram; V1 still available on explicit request)
V2_JUDGE_MODEL Kimi-K2.6 Model that judges candidates + runs the refine pass
V2_FAN_OUT_MODELS Kimi-K2.6,Qwen3.5-397b,GPT-OSS-120b,Step-3.7-Flash Fast pool that ranks keywords + fans out (each writes a full candidate)
V2_RANK_MIN_SCORE 40 Min consensus score (0–100) for a keyword to be kept after multi-agent ranking
V2_RANK_FLOOR 15 Always keep at least this many top-ranked keywords

Google Sheet Columns

Column Description
Batch Date When the run happened
Rank Score rank within this batch
Job Title / Company / Location Job details
Platform LinkedIn / Indeed / Glassdoor
Relevance Score AI assessment (1–10)
ATS Before (%) ATS score on original resume
ATS After (%) ATS score on tailored resume
ATS Improvement After − Before
Resume Quality Structural quality score
Priority High / Medium / Low
Matching / Missing Skills Gap analysis
AI Recommendation LLM reasoning
Apply Link Direct job URL (clickable)
Resume Link Google Drive link to tailored resume
Application Status Dropdown: Not Applied → Offer

Environment Variables (.env) 

NVIDIA_API_KEY=nvapi-...          # GLM 5.1 + primary key
NVIDIA_API_KEY_2=nvapi-...        # DeepSeek-v4-Pro, MiniMax
NVIDIA_API_KEY_3=nvapi-...        # Kimi-K2.6
NVIDIA_API_KEY_4=nvapi-...        # Qwen3.5-122b
NVIDIA_API_KEY_5=nvapi-...        # GPT-OSS-120b
NVIDIA_API_KEY_6=nvapi-...        # DeepSeek-v4-Flash
NVIDIA_API_KEY_7=nvapi-...        # Qwen3.5-397b, Qwen3.5-122b-v2
NVIDIA_API_KEY_8=nvapi-...        # Step-3.7-Flash
GOOGLE_SHEET_ID=1Ehxt3eo...       # Your Google Sheet ID
RESUME_PATH=data/resume/resume.pdf

Logging & Debugging

Every pipeline run writes a timestamped log to data/logs/run_YYYY-MM-DD_HH-MM-SS.log.

To diagnose failures:

  1. Run a search from the UI
  2. Switch to the 📋 Logs tab
  3. Errors show in red, warnings in yellow
  4. Use Download Full Log File to share or inspect offline
  5. Previous runs are also listed in the selector

The log captures:

  • Every scrape attempt (role, location, raw result count)
  • Full Python tracebacks on any exception
  • All print() output from scrapers and LLM clients
  • Playwright browser output

Known Issues / Pending

Issue Status Notes
Google Drive upload 'Client' object has no attribute 'auth' Pending fix gspread auth method mismatch
LLM resumes = 0 (GLM timeout during customization) Pending fix Switch to Kimi/Step for resume generation
Naukri blocked by Akamai Permanent skip Returns 406 / "Access Denied" with Playwright
Google OAuth "Access blocked" Fixed Add email as test user at GCP console
V2 silently dead — NVIDIA NIM returns 404 Open 404 "Function '23d4f03a…': Not found for account 'LaXPGKs0…'" at resume_v2_natural.py L747/L803/L976. V2 falls back to regex/V1 but still reports itself as V2. The 404 names the account, so likely a credential/entitlement issue rather than another EOL model. V1 is unaffected (deterministic by default). Caught only by test_v1_quality::test_v2_natural_ai.
ATS before/after score could decrease Fixed (dba70c7) Three one-sided asymmetries in the before/after comparison — see HISTORY.md and tests/test_score_symmetry.py
test_atomic_scoring::test_porter_fixture_atomic_vs_gram Open (pre-existing) external_ats atomic coverage: 51 vs required 52. Fails on d5a4481 too — not a regression
test_resume_v2::test_place_sentences Open (pre-existing) V2 sentence placement. Fails on d5a4481 too
test_api_parity crashes on Windows Environmental 0x800706be in pdf_writer._word_available — tries to launch MS Word over COM

Running the UI 

streamlit run ui.py
# Opens at http://localhost:8501

# Tabs:
# 1. Search     — configure and run the full pipeline
# 2. Results    — view all assessed jobs with scores
# 3. Job Details — expand any job for full AI breakdown
# 4. Deep Research — Odysseus engine to research companies