ats-engine

# ATS Engine

[![npm](https://img.shields.io/npm/v/@veriworkly/ats-engine)](https://www.npmjs.com/package/@veriworkly/ats-engine)
[![CI](https://github.com/VeriWorkly/ats-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/VeriWorkly/ats-engine/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
![Node 22.12+](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen)

Read a resume the way an applicant tracking system (ATS) does, see what it would store, and get a score with a reason behind every point.

`@veriworkly/ats-engine` is an open-source resume checker from [VeriWorkly](https://veriworkly.com), a privacy-first resume builder. It parses a resume into the fields an ATS keeps, scores it against a [published rubric](./RUBRIC.md), and compares it with a job posting requirement by requirement. The same input always produces the same report. The core does no network calls and keeps no state, so it runs in a browser, at the edge, or on a server.

To try it without installing anything, upload a resume to the [VeriWorkly ATS checker](https://veriworkly.com/ats-checker), which runs on this engine.

[Install](#install) · [Quick start](#quick-start) · [MCP](#use-it-from-an-ai-assistant-mcp) · [GitHub Actions](#use-it-in-github-actions) · [Use it in your app](#use-it-in-your-app) · [AI features](#ai-features) · [Run from source](#run-from-source) · [Documentation](#documentation)

## What it does

- Recovers the fields an ATS stores: name, contact details, each job (title, employer, dates), education on the ISCED scale, skills, certifications (name, issuer, date earned, expiry) and spoken languages with their CEFR level, each group marked with how it was recovered: parsed from the text, read from structured input, or repaired by a model.
- Scores readiness from 0 to 100 across parsing, contact, structure, content, format and writing, minus any integrity penalties. Every failed check comes with evidence and a suggested fix.
- Notes writing style in English resumes: bullets in the first person or the passive voice, duties instead of actions ("Responsible for"), a role you have left written in the present tense, bullets over 40 words, fewer than 2 or more than 8 bullets in a role, three bullets in a row opening with the same word, and role dates written in more than one format. These rules have their own `writing` category and carry 12 points of weight against 190 for the rest of the rubric, so the score still mostly measures whether an ATS can read the resume. They are left out for resumes in other languages.
- Matches a resume to a job posting. Each requirement is marked met, partly met, missing or unverifiable, with the resume lines that support it. Years of experience, degrees and languages are compared as values, not as keywords: "Fluent German" asks for C1 and is met by German at C1 or above, and "AWS certification" is met by a certification row that names AWS. A clearance is compared by level: "Secret" partly meets "Top Secret" and fully meets "Confidential". A statement about the right to work is read for what it says: "Requires H-1B visa sponsorship" never meets "Authorized to work without sponsorship", and a green card does not meet "Must be a U.S. citizen" (U.S. citizenship is the only citizenship the community policy names). A slash joins skills asked together: "HTML/CSS" asks for HTML and CSS, so HTML alone partly meets it, as AWS alone partly meets "AWS/GCP/Azure"; beside an "or" each part is one of the choices, so React alone meets "React/Redux or Vue". A name written with a slash ("CI/CD", "TCP/IP") stays whole. The posting's keywords are split into hard skills and soft skills ("communication", "teamwork"). A resume claims a soft skill more often than it shows one, so a soft skill counts for a tenth of a named skill in the match score.
- Flags integrity problems: hidden text (white, tiny, off-page or covered), instructions aimed at AI screeners, invisible and look-alike characters, a pasted job posting, and keyword stuffing.
- Gives advice that is never scored: a file name like `Resume_final_v3 (2).pdf`, a file over 2 MB, a password, tracked changes or comments left in a Word document, details that can invite age bias where the region calls for it, and what a named ATS (Greenhouse, Lever, Taleo) documents on its own public pages.
- Reads German and Hindi resumes, and applies US, German and Indian conventions for dates, phone numbers, degrees, and whether a photo or date of birth belongs on the page. [LOCALES.md](./LOCALES.md) explains how to add more.
- Adds optional AI analysis, parse repair and resume conversion with your own API key. Any name, employer, title, school, email, URL or skill a model returns is checked against the resume text and dropped if it is not there.

## Install

```sh
npm install @veriworkly/ats-engine
```

To read PDF and DOCX files on Node, also install the optional peer dependencies:

```sh
npm install pdf-parse@2 pdfjs-dist@5.4.296 mammoth
```

The core runs on Node 22.12 or later and in any modern browser or edge runtime.

The package is ESM only. From CommonJS on Node 22.12 or later, `require("@veriworkly/ats-engine")` loads it anyway (Node's `require(esm)`); with TypeScript, use `"module": "nodenext"` or `"moduleResolution": "bundler"`.

## Quick start

Score a file from the command line without writing any code. PDF and DOCX files need the optional readers, which `npx` does not install on its own, so install them once with the CLI:

```sh
npm install -g @veriworkly/ats-engine pdf-parse@2 pdfjs-dist@5.4.296 mammoth
ats-engine check resume.pdf --job posting.txt
```

For a one-off run without installing, name the readers to `npx`: `npx -p @veriworkly/ats-engine -p pdf-parse@2 -p pdfjs-dist@5.4.296 -p mammoth ats-engine check resume.pdf`. A `.txt`, `.md`, `.html` or `.json` resume needs none of them: `npx @veriworkly/ats-engine check resume.md`.

```text
Readiness  97/100 (good) — 32/35 checks passed
Job match  77/100
Verdict    strong
  Requirements met: 5 of 9
    [met]          3+ years of professional software engineering experience
    [met]          Bachelor's degree in Computer Science or a related field
    [met]          Strong experience with Go or Java
    [met]          Experience with Kafka or another event-streaming platform
    [partial]      Hands-on experience with Terraform and Kubernetes
    [missing]      Excellent communication and teamwork skills
    [partial]      Fluent Spanish — Spanish: B1 read, C1 asked
    [met]          AWS certification (preferred)
    [missing]      Experience with gRPC (preferred)
  Missing keywords: terraform, payments, grpc, event-streaming, platform, backend
  Missing soft skills (weigh less): communication, teamwork

What an ATS reads:
  Name     Mei Lin Chen
  Email    meilin.chen@example.com
  Phone    (512) 555-0193
  Role     Software Engineer, Globex Corporation (Jul 2022 – Present)
  Role     Software Developer Intern, Initech (May 2021 – Aug 2021)
  Role     Teaching Assistant, UT Austin Department of Computer Science (Jan 2020 – May 2022)
  Tenure   6 yr 9 mo
  Skills   Go, Java, Python, TypeScript, Kafka, Redis, PostgreSQL, Docker, Kubernetes, AWS, Git
  Cert     AWS Certified Developer - Associate, Amazon Web Services, Mar 2023, expires Mar 2026
  Speaks   English (native), Mandarin (fluent), Spanish (conversational)

Failed checks:
  [info] Writing: 1 bullet speaks in the first person, such as "I migrated 30 nightly reports from cron jobs to Airflow, saving 6 hours a week.".
      Fix: Leave out "I", "my" and "we": open each bullet with what you did ("Led the payments team").
  [warning] Writing: 1 bullet opens with a duty rather than an action, such as "Responsible for the internal reporting dashboard used by the finance team.".
      Fix: Replace "Responsible for", "Worked on" and the like with the verb for what you did, and say what came of it.
  ...

Advice (not scored):
  [File] The file name does not say whose resume it is, or reads as a draft. Recruiters see it in the ATS and in their downloads, beside everyone else's.
      The file is named "resume.pdf".
      Fix: Name it Mei-Lin-Chen-Resume.pdf.
```

| Option            | What it does                                                                                       |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `--job <file>`    | Match against a job posting (`.txt`, `.pdf`, `.docx` or a saved `.html`) and list each requirement |
| `--policy <file>` | Use your own scoring policy JSON instead of the bundled one                                        |
| `--json`          | Print the full report as JSON, `advice` included                                                   |
| `--min-score <n>` | Exit with code 2 when the readiness score is below `n`, for CI checks                              |
| `--region <code>` | Read the resume as from `US`, `DE` or `IN` instead of guessing                                     |
| `--text`          | Also print the text in the order an ATS reads it (with `--json`, as the report's `lines`)          |
| `--ats <name>`    | Add the documented notes on one ATS (`greenhouse`, `lever`, `taleo`), each with its source         |
| `-h`, `--help`    | Print the options                                                                                  |
| `-v`, `--version` | Print the engine version, for bug reports                                                          |

The resume can be a `.pdf`, `.docx`, `.html`, `.txt` or `.md` file, or a `.json` [JSON Resume](https://jsonresume.org) or `ats-resume@1` document. The exit code is 0 when the check ran, 1 on an error, and 2 when the score is below `--min-score`.

After the failed checks the CLI prints any **advice** under its own heading, "Advice (not scored)". Advice never changes a score. It covers the file itself: a name like