
Problem
Most CV-matching tools either score a CV against a generic template unrelated to the vacancy, or use a language model to rewrite it in ways that quietly invent experience. For structured applications, such as NHS or Civil Service roles scored against a person specification, both approaches give advice that is irrelevant or dishonest.
Solution
The job description is treated as the benchmark. Each requirement is classified into exactly one of four outcomes: direct evidence, transferable evidence, needs stronger evidence, or a genuine gap. Missing requirements are removed before any statement text is generated, so there is no code path that writes a sentence about something the candidate has not done.
Architecture
CV ─────────▶ cv_parser ─────────▶ structured CV
Target JD ──▶ job_parser ────────▶ categorised requirements
Similar JDs ▶ similar_jobs ▶ requirement_miner ▶ frequency_analyser
│
▼
evidence_mapper ▶ gap_analyser ▶ personal_statement
│ (optional ai_phrasing, guarded)
▼
statement_quality ▶ optimiser ▶ report_generator (DOCX/PDF)
Each module has one job and its own test file. The CLI (app.py) and the Streamlit UI (streamlit_app.py) contain no analysis logic; both call the same orchestration functions.
Technologies
| Purpose | Library |
|---|---|
| PDF and DOCX parsing | pdfplumber, python-docx |
| Report export | reportlab (PDF), python-docx (DOCX) |
| Web interface | Streamlit |
| Optional AI layer | requests against any OpenAI-compatible endpoint, python-dotenv for configuration |
| Testing | pytest |
Matching is deliberately rule-based (a curated vocabulary with word-boundary regular expressions) so every match traces to a literal phrase rather than an opaque model decision.
Implementation highlights
- Evidence matrix: for each requirement it records how often it appears across similar adverts, how the target role frames it (essential, desirable, responsibility, competency), and the exact CV section and snippet that supports it.
- Frequency is reported, not weighted: “8/10 similar adverts” is shown as a fact and never overrides the target job description’s own framing.
- Three statement tiers: Master (reusable for a role), Industry (adapted to a sector) and Vacancy (tailored to one advert), with Coverage, Evidence, Keyword Relevance and Natural Language indicators and a 13-point checklist, labelled as indicators rather than a guarantee.
- Reviewable suggestions: before/after wording changes appear only where genuine evidence supports them, and each one is approved individually.
Applied AI, with a guardrail
An optional layer (ai_phrasing.py) can send a generated statement to an OpenAI-compatible model to improve its flow. It is off by default and the application works fully without it. The prompt forbids new facts, but the prompt is not trusted on its own: the response is checked against the gap analysis, and if any phrase the CV cannot evidence appears, the AI output is rejected and the rule-based text is kept. No API key is stored in the code; configuration comes from environment variables.

Results
- A working CLI and Streamlit application with DOCX and PDF report export.
- 117 automated tests across 14 test modules passed when run locally on 12 November 2026 (the README’s older count is 101).
- No outcome metrics are claimed: the tool has not been evaluated on hiring results.
Limitations
- Rule-based matching depends on the curated vocabulary; unfamiliar phrasing can be missed until the vocabulary is extended.
- There is no hosted demo; it runs locally with
streamlit run streamlit_app.py. - Quality scores are simple, inspectable calculations, not predictions of interview success.
What this project demonstrates
- Python application design: single-purpose modules, shared orchestration and two thin interfaces.
- Testing discipline: a test file for every module.
- Responsible AI integration: optional, configurable, and verified after the fact rather than trusted.
- Document processing: PDF and DOCX parsing in, DOCX and PDF reports out.
Written by Emmanuel Abolade, Data Analyst, Business Intelligence Developer and Full-Stack Software Developer based in Hull, UK. Every figure on this page comes from the linked public repository or live demo.