Metadata-Version: 2.4
Name: ats-resume-checker
Version: 0.2.0
Summary: ATS resume analyzer for keyword matching and scoring
Author: Vidhi Bhutia
License: MIT
Keywords: ATS,resume,resume analyzer,job matching,resume score
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyPDF2
Requires-Dist: scikit-learn
Requires-Dist: nltk
Requires-Dist: python-docx
Dynamic: license-file

# ats-resume-checker

[![PyPI version](https://img.shields.io/pypi/v/ats-resume-checker)](https://pypi.org/project/ats-resume-checker/)
[![Python](https://img.shields.io/pypi/pyversions/ats-resume-checker)](https://pypi.org/project/ats-resume-checker/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A lightweight Python package that scores resumes against job descriptions for ATS (Applicant Tracking System) compatibility — runs fully locally, no external AI APIs required.

---

## Features

- **Multi-format support** — PDF, DOCX, and plain TXT resumes
- **TF-IDF similarity scoring** — more accurate than simple word-count matching
- **Smart keyword extraction** — lemmatization, bigrams, and a built-in library of 30+ recognized multi-word skills (`"machine learning"`, `"rest api"`, `"data analysis"`, etc.)
- **Keyword gap analysis** — shows exactly which JD keywords are present or missing in the resume
- **Keyword match rate** — percentage of job description keywords covered
- **Resume word count** — flags resumes that are too short or too long
- **Actionable suggestions** — concrete tips to improve ATS compatibility
- **CLI** — run analysis directly from your terminal without writing any code

---

## Installation

```bash
pip install ats-resume-checker
```

---

## Quick Start

```python
from ats_resume_checker import analyze_resume

result = analyze_resume(
    "resume.pdf",   # supports .pdf, .docx, and .txt
    "Looking for a Python developer with SQL and machine learning experience."
)

print(result)
```

### Output

```python
{
    "ats_score": 54.30,           # TF-IDF cosine similarity score (0–100)
    "match_rate": 66.7,           # % of JD keywords found in the resume
    "matched_keywords": [
        "data analysis",
        "machine learning",
        "python",
        "sql"
    ],
    "missing_keywords": [
        "communication",
        "developer",
        "problem solving"
    ],
    "resume_word_count": 520,
    "suggestions": [
        "Include more job-specific keywords. Missing: communication, developer, problem solving.",
        "Quantify achievements where possible (e.g. 'Improved performance by 30%')."
    ]
}
```

---

## Python API

### `analyze_resume(resume_path, job_description)`

| Parameter | Type | Description |
|---|---|---|
| `resume_path` | `str` | Path to the resume file (`.pdf`, `.docx`, or `.txt`) |
| `job_description` | `str` | Plain-text job description |

Returns a `dict` with `ats_score`, `match_rate`, `matched_keywords`, `missing_keywords`, `resume_word_count`, `suggestions`.

---

### Utility functions

```python
from ats_resume_checker import extract_text, extract_keywords, get_keyword_set

# Extract text from any supported file type
text = extract_text("resume.pdf")

# Get a ranked list of keywords (includes bigrams and known phrases)
keywords = extract_keywords(text, top_n=30)

# Get a clean keyword set (unigrams + known phrases only, no noise)
kw_set = get_keyword_set(text, top_n=50)
```

---

## Command-Line Interface

After installation the `ats-check` command is available in your terminal:

```bash
# Job description as a string
ats-check resume.pdf "Python developer with SQL and machine learning skills"

# Job description as a .txt file
ats-check resume.docx job_description.txt

# Output as JSON (useful for scripts and pipelines)
ats-check resume.pdf "Data engineer with Spark experience" --json
```

### Example output

```
==============================================
   ATS RESUME ANALYSIS REPORT
==============================================
  ATS Score       : 54.30%
  Keyword Match   : 66.7%
  Resume Words    : 520

  Matched Keywords (4):
    + data analysis
    + machine learning
    + python
    + sql

  Missing Keywords (3):
    - communication
    - developer
    - problem solving

  Suggestions:
    * Include more job-specific keywords. Missing: communication, developer, problem solving.
    * Quantify achievements where possible.
==============================================
```

---

## Dependencies

| Package | Purpose |
|---|---|
| `PyPDF2` | PDF text extraction |
| `python-docx` | DOCX text extraction |
| `scikit-learn` | TF-IDF vectorization and cosine similarity |
| `nltk` | Lemmatization, stopwords, tokenization |

All dependencies are installed automatically with `pip install ats-resume-checker`.

---

## License

MIT © Vidhi Bhutia
