Skip to content
BranchesTags

Repository files navigation

ATS Resume Scorer

An intelligent Applicant Tracking System (ATS) Resume Scorer powered by local AI (Ollama) that analyzes resumes against job descriptions to provide comprehensive scoring, skill matching, and improvement recommendations. Built for both job seekers and hiring managers.

Key Features

AI-Powered Skill Extraction

  • Ollama Integration: Local LLM for intelligent skill extraction from job descriptions
  • No External APIs: Everything runs locally - maximum privacy and performance
  • Adaptive Skills: Discovers relevant skills without hardcoded lists
  • Dual Mode Support:
    • Explicit Skills: Hiring managers provide specific skills (fast: 10-15s)
    • AI Extraction: Leave empty, system discovers skills automatically (smart: 20-30s)

For Job Seekers

  • Resume Optimization: Get personalized suggestions to improve ATS compatibility
  • Skill Gap Analysis: Identify missing technical skills with AI-assisted discovery
  • ATS Score: Understand how well your resume performs against ATS systems
  • Actionable Feedback: Receive specific recommendations for resume enhancement
  • Smart Matching: Fuzzy matching finds related skills you might not realize you have

For Hiring Managers

  • Candidate Evaluation: Assess resume quality and job fit
  • AI-Assisted Skill Extraction: Automatically discover relevant skills from job descriptions
  • Flexible Skill Input: Provide explicit skills OR let AI extract them
  • Smart Skill Matching: Fuzzy matching with confidence scoring
  • Suitability Assessment: Clear recommendations on candidate suitability
  • Profile Analysis: Balanced view of candidate strengths and weaknesses

Core Functionality

  • PDF Processing: Advanced text extraction from PDF resumes
  • Technical Skill Detection:
    • AI-powered extraction using Ollama (when available)
    • TF-IDF based extraction (fallback)
    • 60+ predefined cloud/tech skills in knowledge base
  • Advanced Skill Matching:
    • Exact matching (confidence: 1.0)
    • Partial multi-word matching (confidence: 0.95)
    • Fuzzy string matching (threshold: 0.6)
    • Word boundary detection
  • Intelligent Scoring: 90% skills weight + 10% content similarity
  • Multi-Role Interface: Separate optimized experiences for job seekers and recruiters
  • Graceful Degradation: Works perfectly even without Ollama installed

Tech Stack

  • Backend: Python 3.8+, Flask
  • AI Engine: Ollama (local LLM, optional)
  • Text Processing: NLTK, scikit-learn, FuzzyWuzzy
  • PDF Parsing: PyPDF2
  • Frontend: HTML5, CSS3, Vanilla JavaScript
  • Deployment: Ready for Docker/Gunicorn deployment

Prerequisites

  • Python 3.8 or higher
  • pip package manager
  • Virtual environment (recommended)
  • Ollama (optional, for AI features - see installation below)

Installation

Basic Setup (Without AI)

  1. Clone the repository

    git clone https://github.com/prafullb3/ATS-Resume-checker.git
cd ATS-Resume-checker

  2. Create virtual environment

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Install dependencies

    pip install -r requirements.txt

  4. Download NLTK data (required for text processing)

    python -c "import nltk; nltk.download('punkt'); nltk.download('stopwords')"

  5. Run the application

    python app.py

    Visit: http://localhost:5000

Advanced Setup (With Ollama AI)

For intelligent AI-powered skill extraction and analysis:

Option 1: macOS (Homebrew)

# Install Ollama
brew install ollama

# Start Ollama service
brew services start ollama

# Pull mistral model (recommended - 4GB, fast)
ollama pull mistral

# Or pull other models:
ollama pull llama2      # Larger, slower
ollama pull neural-chat # Smaller, faster

Option 2: Linux/Windows/Docker

Download and install from ollama.ai

# Start Ollama
ollama serve

# In another terminal, pull a model
ollama pull mistral

Option 3: Automated Setup (macOS/Linux)

# Run the automated setup script
python setup_ollama.py

# Or manually:
bash setup_ollama.sh

Verify Ollama is running:

curl http://localhost:11434/api/tags

Should return a JSON list of available models.

Install Python dependencies for Ollama support:

pip install requests>=2.31.0

Now the system will automatically use Ollama for AI features when available!

Usage

Running the Application

  1. Start the server

    python app.py

  2. Open in browser

    http://localhost:5000

  3. Optional: Start Ollama service (for AI features)

    # macOS
ollama serve

# Or if installed as service
brew services start ollama

User Workflows

Job Seeker Portal (/)

  1. Upload your resume (PDF format)
  2. Paste target job description
  3. Click "Score Resume"
  4. Get detailed analysis with:
    • Overall ATS score
    • Matched skills
    • Missing skills
    • Improvement suggestions

Example:

Resume: "5 years Python development, AWS experience, built REST APIs..."
Job: "Seeking Python developer with AWS and Docker skills..."
Result: Score 78/100, missing Docker, suggestions to add it

Hiring Manager Portal (/hiring-manager)

Option 1: With Explicit Skills (Fast)

1. Enter required skills: "Python, AWS, Docker, Kubernetes"
2. Upload candidate resume
3. Paste job description (optional, for context)
4. Click "Analyze"
5. Get skill matching results in 10-15 seconds

Option 2: With AI Extraction (Smart)

1. Leave "Required Skills" field EMPTY
2. Upload candidate resume
3. Paste full job description
4. Click "Analyze"
5. Ollama extracts 20-30 relevant skills automatically
6. Get intelligent matching results in 20-30 seconds

Option 3: Hybrid (Recommended)

1. Enter core skills: "Python, AWS"
2. Leave rest for AI extraction
3. Upload resume + paste job description
4. Get combined explicit + AI-discovered skills

API Reference

POST /score

Analyze a resume against job requirements.

Request:

curl -X POST http://localhost:5000/score \
  -F "resume=@resume.pdf" \
  -F "job_description=Job description text here" \
  -F "required_keywords=Python,AWS,Docker"

Parameters:

  • resume (file): PDF resume file (required)
  • job_description (string): Job requirements text (required)
  • required_keywords (string, optional): Comma-separated skills
    • If provided: Uses explicit skill matching (fast)
    • If empty: AI extracts skills from job_description (smart)

Response:

{
  "score": 78.5,
  "skills_score": 75.0,
  "content_score": 85.0,
  "matched_keywords": ["python", "aws", "rest api"],
  "missing_keywords": ["docker", "kubernetes"],
  "skills_matched": 3,
  "total_skills": 5,
  "skills_source": "user_provided",
  "ollama_status": "enabled",
  "suggestions": [
    "Add Docker and Kubernetes experience to your resume...",
    "Highlight your AWS certifications..."
  ]
}

#### With Ollama (AI-Powered)

Job Description ↓ Ollama LLM ↓ Extract 20-30 relevant skills

  • Explicit skills mentioned
  • Implicit skill requirements
  • Related technologies
  • Best practices and tools

#### Without Ollama (TF-IDF Fallback)

Job Description ↓ TF-IDF Analysis + Pattern Matching ↓ Extract high-frequency technical terms

  • Fast extraction (instant)
  • Still covers ~80% of important skills
  • No AI required

### Advanced Skill Matching

The system uses **four levels of skill matching**:

1. **Exact Match** (Confidence: 1.0)
   - Word-for-word match with word boundaries
   - Example: "Python" matches "Python" but not "Jython"

2. **Partial Match** (Confidence: 0.95)
   - All words in skill present in resume
   - Example: "REST API" matches resume containing both "REST" and "API"

3. **Fuzzy Match** (Confidence: 0.6-0.9)
   - Similar spelling/abbreviations
   - Example: "JS" matches "JavaScript", "AWS EC2" matches "Amazon EC2"

4. **Context Match** (With Ollama)
   - Deep semantic understanding
   - Example: "Kubernetes" context matches "container orchestration"

### Scoring Methodology

Overall Score = (Skills Score × 0.90) + (Content Score × 0.10)

Where:

  • Skills Score: Percentage of required skills found in resume Calculation: (Matched Skills / Total Required Skills) × 100

  • Content Score: TF-IDF cosine similarity Calculation: Similarity between resume text and job description

  • Weighting: 90% skills (technical fit) 10% content (contextual relevance)


### Example Scoring

**Scenario: Python Developer Role**

Required Skills: `Python, Django, PostgreSQL, Docker, AWS, REST API` (6 skills)

Resume mentions: `Python, Django, PostgreSQL, REST API` (4 skills)

Skills matched: 4/6 = 66.7% Content similarity: 78%

Score = (66.7 × 0.90) + (78 × 0.10) = 60.0 + 7.8 = 67.8/100


Missing skills: Docker, AWS
Suggestions: "Add Docker containerization and AWS deployment experience"

### Key Improvements Over Standard ATS

Intelligent Detection: Not just keyword matching  
Fuzzy Matching: Handles abbreviations and variations  
Multi-word Skills: Understands "REST API", "Machine Learning", etc.  
Context Aware: Uses Ollama for semantic understanding  
Industry Agnostic: Works across all technical fields  
Adaptive: Skills extracted from actual job descriptions


### Key Files Breakdown

**Core Scoring Engine**
- `scorer.py` (14KB) - Main scoring algorithm with weighted skill matching
- `skill_weights.py` (7.2KB) - 179 skills organized by category with importance weights

**AI & Optimization**
- `ollama_scorer.py` (6.2KB) - Local LLM integration for intelligent skill extraction
- `cache.py` (8.5KB) - Intelligent caching (job descriptions, resumes, skills)
- `utils.py` (7.5KB) - Shared utilities (text processing, JSON parsing, error handling)

**Flask Application**
- `app.py` (3.9KB) - Flask routes, endpoints, form handling
- `pdf_parser.py` (238B) - PDF text extraction

**Setup & Configuration**
- `performance_config.py` (1.7KB) - Performance modes (FAST, BALANCED, QUALITY)
- `setup_ollama.py` (5.3KB) - Automated Ollama installation and setup

## Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines
- Write clear, concise commit messages
- Add tests for new features
- Update documentation as needed
- Ensure code passes linting checks

## Privacy & Security

- Resumes are processed temporarily and not stored permanently
- All analysis happens locally on your machine
- **No data transmitted to external services** (Ollama runs locally)
- Open-source and transparent processing
- SSL/TLS ready for production deployment

## Performance Metrics

| Metric | FAST | BALANCED | QUALITY |
|--------|------|----------|---------|
| Speed | 10-15s | 20-30s | 40-60s |
| Skill Extraction | TF-IDF | TF-IDF or User | Ollama LLM |
| Accuracy | 80% | 85% | 90%+ |
| AI Analysis | None | Optional | Full |
| Best For | Batch | General Use | Deep Review |

## ⚙️ Configuration & Performance

### Performance Modes

Choose based on your needs:

#### FAST Mode (10-15 seconds)
```python
# In performance_config.py or app.py
DEFAULT_MODE = PerformanceConfig.FAST

Features:
- TF-IDF skill extraction only
- No Ollama calls
- Best for batch processing

BALANCED Mode (20-30 seconds) Recommended

DEFAULT_MODE = PerformanceConfig.BALANCED

Features:
- User-provided or TF-IDF skills (fast)
- Optional Ollama for deep analysis
- Good balance of speed and intelligence

QUALITY Mode (40-60 seconds)

DEFAULT_MODE = PerformanceConfig.QUALITY

Features:
- Ollama LLM for intelligent extraction
- Full AI analysis and suggestions
- Best for single candidate deep review

Ollama Configuration

Model Selection

Mistral (Recommended - 4GB)

ollama pull mistral
# Fast, efficient, good quality
# Best for most use cases

Neural Chat (Lightweight - 2.7GB)

ollama pull neural-chat
# Fastest extraction
# Good for high-volume processing

Llama 2 (Powerful - 7GB)

ollama pull llama2
# Better quality, slower
# Best for complex analysis

Customization

Environment variables in app.py:

OLLAMA_HOST = "http://localhost:11434"  # Ollama service address
OLLAMA_TIMEOUT = 10                      # Timeout in seconds
OLLAMA_MODEL = "mistral"                 # Model to use
SKILL_EXTRACTION_MODEL = "mistral"       # Can differ if needed

Predefined Skills Dictionary

System includes 60+ predefined skills across:

Azure

  • Virtual Machines, App Service, Functions, Logic Apps
  • SQL Database, Cosmos DB, Storage Accounts
  • Key Vault, API Management, Service Bus
  • Azure AD, VPN Gateway, ExpressRoute
  • Backup/Disaster Recovery

AWS

  • EC2, S3, Lambda, RDS, DynamoDB
  • CloudFormation, CloudFront, Route53
  • VPC, IAM, Security Groups
  • ECS, EKS, Elastic Beanstalk

GCP

  • Compute Engine, App Engine, Cloud Functions
  • Cloud SQL, Firestore, BigQuery
  • Cloud Storage, Load Balancing
  • VPC, Cloud IAM

General DevOps

  • Docker, Kubernetes, Jenkins
  • GitLab CI, GitHub Actions
  • Terraform, Ansible
  • Prometheus, ELK Stack

Troubleshooting

Ollama Not Detected

If you see "Ollama Status: disabled" in results:

  1. Check if Ollama is running

    curl http://localhost:11434/api/tags

  2. If not running, start it

    # macOS
brew services start ollama
ollama serve

# Linux/Docker
ollama serve

  3. Verify a model is pulled

    ollama list
# Should show: mistral, neural-chat, or llama2

  4. If no models, pull one

    ollama pull mistral

Slow Performance

  • Using QUALITY mode? Try BALANCED or FAST
  • Ollama running on weak hardware? Try faster model (neural-chat)
  • Resume very large? PDF parsing takes time - normal

Resume Parsing Errors

Error: "Could not extract text from PDF"
  • Verify PDF is valid and not corrupted
  • Try opening in Adobe Reader first
  • Check file permissions

Skills Not Being Extracted

  1. Check Ollama model is loaded

    ollama list

  2. Verify job description is clear

    • Use detailed, complete job descriptions
    • Include technical requirements section

  3. Try explicit skills instead

    • Enter skills directly in textarea
    • More reliable for critical skills

Documentation

Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Write clear, concise commit messages
  • Add tests for new features
  • Update documentation as needed
  • Follow PEP 8 style guidelines
  • Use type hints where appropriate
  • Ensure code passes linting checks

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support & Contact

Quick Start Guide

For Job Seekers (5 minutes)

1. Start app: python app.py
2. Go to: http://localhost:5000
3. Upload your resume (PDF)
4. Paste a job description
5. Get your ATS score and improvement tips!

For Hiring Managers (5 minutes)

1. Start app: python app.py
2. Go to: http://localhost:5000/hiring-manager
3. Option A - Enter skills: "Python, AWS, Docker"
   Option B - Leave empty for AI extraction
4. Upload resume + paste job description
5. Get comprehensive candidate evaluation!

With Ollama AI (Optional, adds intelligence)

1. Install: brew install ollama (macOS)
2. Pull model: ollama pull mistral
3. Run: ollama serve
4. Now app uses AI for skill extraction!
5. Try both options above again - notice better results!

Made with ❤️ for hiring teams and job seekers worldwide

About

ATS Resume Scorer is an intelligent web application that analyzes PDF resumes against job descriptions, providing ATS compatibility scores, technical skill matching, and personalized improvement suggestions. Built with Python and Flask, it serves both job seekers looking to optimize their resumes and hiring managers evaluating candidates.

prafullb3.github.io/ATS-Resume-checker/

Topics

atscssflaskflask-applicationhtmlpythonresume

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages