Hiring Agent: An AI Resume Screening Agent in Python
/hiring-agent
Reach for Hiring Agent if you want a self-hosted, explainable way to turn resumes into structured scores you control โ it runs locally on Ollama, shows evidence and deductions per category, and folds in GitHub activity. Skip it, or keep a human firmly in the loop, if you'd treat the score as a hiring decision: any automated resume screener can absorb bias from its model and prompts, and this is a young project with no public accuracy or fairness track record.
Resume Screening Without an Audit Trail
Screening a stack of resumes by hand is slow and inconsistent, and pasting each PDF into a chatbot loses structure and leaves no audit trail. Hiring Agent exists to make that first pass repeatable: it converts a resume PDF into structured JSON, scores it against fixed criteria, and records the evidence behind each number so a reviewer can see why a candidate landed where they did.
From Resume PDF to a Scored JSON Object
Hiring Agent is an open-source (MIT) AI resume screening agent written in Python that runs a resume from PDF to score. It uses PyMuPDF to convert the PDF to Markdown-like text, calls an LLM per section with Jinja templates to build a JSON Resume object, enriches that with GitHub profile and repo signals, then runs an evaluator that assigns category scores โ open_source, self_projects, production, and technical_skills โ plus bonus points, deductions, and an explanation. It backs either local Ollama models or Google Gemini.
Category Scores Backed by GitHub Activity
- โPDF-to-JSON extraction: PyMuPDF converts the resume to text, then an LLM fills a JSON Resume schema section by section (basics, work, education, skills, projects, awards)
- โGitHub enrichment: pulls the candidate's profile and repos and asks the LLM to pick exactly 7 projects above a minimum author-commit threshold
- โCategory scoring in evaluator.py: open_source, self_projects, production, and technical_skills, each with bonus points and deductions
- โEvidence and explanations attached to each score, not just a bare number
- โRuns local via Ollama or hosted via Google Gemini, switched with one env var (LLM_PROVIDER)
- โDevelopment mode caches intermediate JSON and appends every run to resume_evaluations.csv
Local Ollama or a Gemini API Key
Clone the repo, create a Python 3.11+ virtualenv, and `pip install -r requirements.txt`. Then `cp .env.example .env` and set `LLM_PROVIDER` to `ollama` or `gemini`. For local runs, install Ollama, run `ollama serve`, and pull a model such as `ollama pull gemma3:4b`; for Gemini, set `GEMINI_API_KEY`. An optional `GITHUB_TOKEN` raises GitHub API rate limits.
Running score.py on a Single Resume
Run the whole pipeline on one file: `python score.py /path/to/resume.pdf`. It extracts the PDF, fetches GitHub repos if it finds a profile in the resume, prints a readable report of category scores with evidence, and โ when `DEVELOPMENT_MODE=True` in config.py โ caches intermediate JSON under `cache/` and appends a row to `resume_evaluations.csv`. Batch processing beyond looping the CLI yourself is not clearly documented.
A Consistent First Pass Before a Human Reviews
- โขRunning a consistent first-pass screen over a batch of resumes for a technical role
- โขScoring engineering candidates partly on real GitHub activity instead of self-reported skills
- โขProducing an explainable score with evidence a human recruiter can review and override
- โขKeeping resume data on-premise by running the whole pipeline on local Ollama models
An Open-Source Take on a Usually-Closed Problem
Automated hiring is contentious, and an open-source take on it that you can read and run yourself is unusual โ most resume-screening tools are closed SaaS. This one comes from HackerRank, runs fully local so resumes never leave your machine, and has attracted real interest in a transparent alternative.
Every Score Comes With Evidence and Deductions
- โSelf-hostable end to end โ with Ollama, no resume data leaves your machine
- โScores come with evidence, bonus points, and deductions, so a number is traceable to a reason
- โProvider-agnostic: swap between local Ollama and Google Gemini with one env var
- โUses real GitHub activity as a signal, not just the resume's own claims
- โMIT-licensed, readable Python, so you can inspect and change the scoring rules
A Score Should Never Be the Whole Decision
- โณAutomated resume scoring can encode bias from the underlying LLM and its scoring prompts; a score should inform a human and never be the sole hiring decision โ treat the 'fair' framing in the README as a goal, not a guarantee
- โณEvaluation quality is only as good as the model behind it; a small local model like gemma3:1b will score very differently from Gemini, and there is no published accuracy or fairness benchmark
- โณIt needs an LLM backend you set up yourself โ either a running Ollama install with a pulled model, or a Google Gemini API key
- โณGitHub enrichment assumes the candidate lists a GitHub profile with public repos; strong candidates without one get no credit from that stage
- โณYoung project with a narrow CLI โ batch runs, a stable API, and integration hooks aren't clearly documented
Resume-Matcher, LangChain, and Dify
For Teams That Keep a Human Making the Final Call
Engineering hiring teams and recruiters who want a transparent, self-hosted first pass on technical resumes and are willing to keep a human making the actual call. It fits people comfortable running Python and a local LLM who value seeing the evidence behind a score. It's a poor fit if you want a turnkey ATS, need a proven-unbiased scorer, or plan to auto-reject candidates on the number alone.
Hiring Agent FAQ
Hiring Agent is an open-source AI resume screening agent from HackerRank that converts a resume PDF into structured data, enriches it with GitHub activity, and produces category scores with evidence. It runs on local Ollama models or Google Gemini.
The README frames the evaluation as fair and explainable, and it does attach evidence and deductions to each score. But any LLM-based scorer can inherit bias from its model, so the output should support a human reviewer rather than replace one.
Not necessarily. You can run fully local with Ollama and a pulled model like gemma3:4b, or set GEMINI_API_KEY to use Google Gemini instead. A GitHub token is optional and only raises API rate limits.
It extracts a GitHub username from the resume, fetches the profile and repositories, and asks the LLM to select exactly 7 projects above a minimum author-commit threshold, favoring meaningful contributions, then folds that into the score.
Is hiring-agent worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of hiring-agent.