ats-resume-scorer 2.0.0

A comprehensive ATS Resume Scoring Plugin with advanced features including batch processing, web API, and Docker support

🚀 Enhanced ATS Resume Scorer with AI Integration

A comprehensive Python-based plugin to score resumes against ATS standards with AI-powered recommendations and multiple detail levels.

✨ New Features (v2.0)

• 🤖 AI-Enhanced Recommendations: Get intelligent, context-aware suggestions powered by LLMs
• 📊 Multiple Recommendation Levels: Choose between Concise, Normal, and Detailed analysis
• 🔧 LLM Integration: Support for OpenAI, Anthropic, and local models
• ⚡ Enhanced Performance: Improved scoring algorithms and batch processing
• 🌐 Upgraded Web Interface: Modern, responsive UI with AI features

---

🎯 Recommendation Levels

📝 Concise

• Best for: Quick reviews, batch processing
• Output: 3-5 high-priority recommendations
• Focus: Critical issues only

📋 Normal (Default)

• Best for: Regular analysis, balanced detail
• Output: 5-8 recommendations with action steps
• Focus: Important improvements with guidance

🔬 Detailed

• Best for: Deep analysis, comprehensive improvement
• Output: 8+ recommendations with examples, explanations, and step-by-step guides
• Focus: Complete optimization roadmap

---

🚀 Quick Start

1. Installation

# Install the package
pip install ats-resume-scorer

# Install spaCy model
python -m spacy download en_core_web_sm

# Optional: Install LLM dependencies
pip install openai anthropic  # for AI features

2. Basic Usage

# Simple scoring
ats-score --resume resume.pdf --jd job_description.txt

# Choose recommendation level
ats-score --resume resume.pdf --jd job.txt --level detailed

# Enable AI recommendations (requires API key)
export ATS_LLM_ENABLED=true
export ATS_LLM_API_KEY=your-api-key
ats-score --resume resume.pdf --jd job.txt --level detailed

---

🤖 AI Integration Setup

OpenAI Setup

export ATS_LLM_ENABLED=true
export ATS_LLM_PROVIDER=openai
export ATS_LLM_API_KEY=sk-your-openai-key
export ATS_LLM_MODEL=gpt-3.5-turbo  # or gpt-4

Anthropic Claude Setup

export ATS_LLM_ENABLED=true
export ATS_LLM_PROVIDER=anthropic
export ATS_LLM_API_KEY=your-anthropic-key
export ATS_LLM_MODEL=claude-3-sonnet

Google Gemini Setup

export ATS_LLM_ENABLED=true
export ATS_LLM_PROVIDER=gemini
export ATS_LLM_API_KEY=your-gemini-api-key
export ATS_LLM_MODEL=gemini-pro  # or gemini-1.5-pro

Local Model Setup (Ollama)

export ATS_LLM_ENABLED=true
export ATS_LLM_PROVIDER=local
export ATS_LLM_ENDPOINT=http://localhost:11434/api/generate
export ATS_LLM_MODEL=llama3.2:latest

---

📚 Complete Usage Guide

🔧 Command Line Interface

Basic Commands

# Standard analysis
ats-score --resume resume.pdf --jd job.txt

# Concise recommendations (great for quick review)
ats-score --resume resume.pdf --jd job.txt --level concise

# Normal recommendations (balanced detail)
ats-score --resume resume.pdf --jd job.txt --level normal

# Detailed analysis (comprehensive guidance)
ats-score --resume resume.pdf --jd job.txt --level detailed

# Save results to file
ats-score --resume resume.pdf --jd job.txt --output results.json
ats-score --resume resume.pdf --jd job.txt --output report.txt --format text

AI-Enhanced Commands

# Enable AI recommendations
ats-score --resume resume.pdf --jd job.txt --level detailed --enable-llm

# Use specific AI provider
ats-score --resume resume.pdf --jd job.txt --enable-llm --llm-provider anthropic
ats-score --resume resume.pdf --jd job.txt --enable-llm --llm-provider gemini

# Custom AI model
ats-score --resume resume.pdf --jd job.txt --enable-llm --llm-model gpt-4
ats-score --resume resume.pdf --jd job.txt --enable-llm --llm-provider gemini --llm-model gemini-1.5-pro

Advanced Features

# Custom scoring weights
ats-score --resume resume.pdf --jd job.txt --weights custom_weights.json

# Custom skills database
ats-score --resume resume.pdf --jd job.txt --skills-db my_skills.json

# Verbose output with debugging
ats-score --resume resume.pdf --jd job.txt --verbose

🎛️ Advanced CLI Tool

Single Resume Analysis

# Basic analysis
python cli_advanced.py single --resume resume.pdf --jd job.txt

# AI-enhanced detailed analysis
python cli_advanced.py single \
  --resume resume.pdf \
  --jd job.txt \
  --level detailed \
  --enable-llm \
  --llm-provider gemini

# Custom configuration
python cli_advanced.py single \
  --resume resume.pdf \
  --jd job.txt \
  --weights custom_weights.json \
  --enable-llm \
  --llm-model gpt-4 \
  --output detailed_report.json

Batch Processing

# Process multiple resumes
python cli_advanced.py batch \
  --resume-dir ./resumes \
  --jd job_description.txt \
  --level concise \
  --output batch_results.csv

# Parallel processing with AI
python cli_advanced.py batch \
  --resume-dir ./resumes \
  --jd job.txt \
  --parallel \
  --workers 4 \
  --enable-llm \
  --level normal

Resume Comparison

# Compare multiple resumes
python cli_advanced.py compare \
  --resumes resume1.pdf resume2.pdf resume3.pdf \
  --jd job.txt \
  --level normal \
  --enable-llm

# Compare with detailed AI analysis
python cli_advanced.py compare \
  --resumes *.pdf \
  --jd job.txt \
  --level detailed \
  --enable-llm \
  --output comparison_report.json

Deep Analysis

# Comprehensive analysis
python cli_advanced.py analyze \
  --resume resume.pdf \
  --jd job.txt \
  --level detailed \
  --enable-llm \
  --output deep_analysis.json

🌐 Web Interface

Start Web Server

# Basic server
python web_api.py

# With AI features enabled
export ATS_LLM_ENABLED=true
export ATS_LLM_API_KEY=your-key
python web_api.py --enable-llm

# Custom configuration
python web_api.py --host 0.0.0.0 --port 8080 --reload

API Usage Examples

Score Single Resume:

curl -X POST http://localhost:8000/score-resume/ \
  -F "resume_file=@resume.pdf" \
  -F "job_description=Python developer position..." \
  -F "recommendation_level=detailed" \
  -F "enable_llm=true"

Batch Processing:

curl -X POST http://localhost:8000/batch-score/ \
  -F "resume_files=@resume1.pdf" \
  -F "resume_files=@resume2.pdf" \
  -F "job_description=Job description text..." \
  -F "recommendation_level=normal"

Check LLM Status:

curl http://localhost:8000/api/llm-status

---

📝 Configuration Files

Custom Weights Example

{
    "keyword_match": 0.40,
    "title_match": 0.05,
    "education_match": 0.05,
    "experience_match": 0.20,
    "format_compliance": 0.10,
    "action_verbs_grammar": 0.10,
    "readability": 0.10
}

LLM Configuration Example

{
    "enabled": true,
    "provider": "openai",
    "model": "gpt-4",
    "api_key": "your-api-key",
    "max_tokens": 500,
    "temperature": 0.7
}

Custom Skills Database Example

{
    "ai_ml": [
        "machine learning", "deep learning", "neural networks",
        "tensorflow", "pytorch", "scikit-learn", "nlp"
    ],
    "blockchain": [
        "blockchain", "ethereum", "smart contracts", "solidity", "web3"
    ],
    "cloud_native": [
        "kubernetes", "docker", "microservices", "serverless", "istio"
    ]
}

---

🎯 Example Outputs

Concise Level Output

🎯 ATS Score: 78.5/100 (Grade: B)
🤖 ATS Compatibility: Good

💡 Recommendations (CONCISE Level):
1. Add these critical missing skills: Docker, Kubernetes, AWS
2. Include a professional email address
3. Quantify your achievements with numbers and percentages

Normal Level Output

🎯 ATS Score: 78.5/100 (Grade: B)
🤖 ATS Compatibility: Good
✨ AI-Enhanced Recommendations

📊 Detailed Breakdown:
🟢 Keyword Match: 85.2/100
🟡 Format Compliance: 72.3/100
🔴 Experience Match: 45.1/100

💡 Recommendations (NORMAL Level):
1. Add these critical missing skills: Docker, Kubernetes, AWS
   📝 Action Steps:
   • Add 'Docker' to your skills section
   • Include containerization experience in job descriptions

2. Quantify your achievements with numbers and percentages
   📝 Action Steps:
   • Replace vague statements with specific metrics
   • Include percentage improvements and team sizes

Detailed Level Output

🎯 ATS Score: 78.5/100 (Grade: B)
🤖 ATS Compatibility: Good
✨ AI-Enhanced Recommendations

📋 Detailed Action Plans:

1. Add these critical missing skills: Docker, Kubernetes, AWS
   📊 Priority: High | Impact: Could increase keyword match by 15-25 points
   📝 Explanation: These containerization and cloud skills are explicitly required
   🎯 Action Steps:
      • Add 'Docker, Kubernetes, AWS' to your technical skills section
      • Include containerization experience in job descriptions
      • Mention specific AWS services you've used (EC2, S3, RDS)
      • Add any container orchestration projects
   💭 Examples:
      • "Skills: Python, JavaScript, Docker, Kubernetes, AWS"
      • "Deployed applications using Docker containers on AWS ECS"

---

🐳 Docker Usage

Quick Start with Docker

# Build and run
cd Docker
make up

# Access services
open http://localhost:8000  # Web interface
open http://localhost:8000/docs  # API docs

# Enable AI features
echo "ATS_LLM_ENABLED=true" >> .env
echo "ATS_LLM_API_KEY=your-key" >> .env
make restart

Docker Commands

# Start all services
make up

# Enable AI with environment variables
ATS_LLM_ENABLED=true ATS_LLM_API_KEY=your-key make up

# Batch processing
make shell
python cli_advanced.py batch --resume-dir /app/data --jd /app/data/job.txt --enable-llm

# View logs
make logs-api

---

🎨 Python API Examples

Basic Usage

from ats_resume_scorer import ATSResumeScorer

# Simple scoring
scorer = ATSResumeScorer()
result = scorer.score_resume('resume.pdf', 'job description text')
print(f"Score: {result['overall_score']}/100")

AI-Enhanced Scoring

from ats_resume_scorer import ATSResumeScorer
from ats_resume_scorer.utils.report_generator import LLMConfig

# Configure Gemini AI-enhanced scoring
llm_config = LLMConfig(
    enabled=True,
    provider="gemini",
    model="gemini-pro",
    api_key="your-gemini-api-key"
)

scorer = ATSResumeScorer(llm_config=llm_config)
result = scorer.score_resume('resume.pdf', 'job description', 'detailed')

print(f"AI Enhanced: {result['llm_enhanced']}")
print(f"Score: {result['overall_score']}/100")
for rec in result['detailed_recommendations'][:3]:
    print(f"- {rec['message']}")
    if rec.get('action_steps'):
        for step in rec['action_steps'][:2]:
            print(f"  • {step}")

Batch Processing

from ats_resume_scorer import ATSResumeScorer

scorer = ATSResumeScorer()
resume_files = ['resume1.pdf', 'resume2.pdf', 'resume3.pdf']
job_description = "Python developer position..."

results = scorer.batch_score_resumes(
    resume_files, 
    job_description, 
    recommendation_level='concise',
    max_workers=4
)

for result in results:
    if result['success']:
        print(f"{result['file_name']}: {result['result']['overall_score']:.1f}/100")
    else:
        print(f"{result['file_name']}: Error - {result['error']}")

Custom Configuration

from ats_resume_scorer import ATSResumeScorer, ScoringWeights
from ats_resume_scorer.utils.report_generator import LLMConfig

# Custom weights (emphasize skills matching)
weights = ScoringWeights(
    keyword_match=0.40,
    experience_match=0.25,
    format_compliance=0.15,
    title_match=0.05,
    education_match=0.05,
    action_verbs_grammar=0.05,
    readability=0.05
)

# LLM configuration
llm_config = LLMConfig(
    enabled=True,
    provider="gemini",
    model="gemini-1.5-pro",
    api_key="your-gemini-api-key",
    temperature=0.5
)

scorer = ATSResumeScorer(weights=weights, llm_config=llm_config)
result = scorer.score_resume('resume.pdf', job_description, 'detailed')

API Integration Example

import requests
import json

# Score resume via API
files = {'resume_file': open('resume.pdf', 'rb')}
data = {
    'job_description': 'Python developer position...',
    'recommendation_level': 'detailed',
    'enable_llm': 'true',
    'llm_provider': 'gemini'
}

response = requests.post('http://localhost:8000/score-resume/', files=files, data=data)
result = response.json()

if result['status'] == 'success':
    print(f"Score: {result['result']['overall_score']}/100")
    print(f"AI Enhanced: {result['llm_enhanced']}")
    
    # Display recommendations by level
    level = result['recommendation_level']
    if level == 'detailed':
        for rec in result['result']['detailed_recommendations'][:3]:
            print(f"\n{rec['message']}")
            if rec.get('action_steps'):
                for step in rec['action_steps']:
                    print(f"  • {step}")
    else:
        for i, rec in enumerate(result['result']['recommendations'][:5], 1):
            print(f"{i}. {rec}")

---

🔧 Environment Variables

# Core Settings
ATS_LLM_ENABLED=true                    # Enable/disable AI features
ATS_LLM_PROVIDER=gemini                 # AI provider (openai/anthropic/gemini/local)
ATS_LLM_MODEL=gemini-pro                # Model name
ATS_LLM_API_KEY=your-api-key            # API key for the provider

# Advanced LLM Settings
ATS_LLM_MAX_TOKENS=500                  # Maximum tokens per request
ATS_LLM_TEMPERATURE=0.7                 # Temperature for generation
ATS_LLM_ENDPOINT=http://localhost:11434 # Custom endpoint for local models

# Application Settings
LOG_LEVEL=INFO                          # Logging level
DEBUG=false                             # Debug mode
MAX_FILE_SIZE=10485760                  # Max file size (10MB)

---

📊 Scoring Breakdown

Categories Explained

Category	Weight	Description
Keyword Match	30%	Skills and requirement alignment
Experience Match	15%	Relevant experience years and domain
Format Compliance	15%	ATS-friendly formatting
Action Verbs & Grammar	10%	Professional language usage
Title Match	10%	Job title alignment
Education Match	10%	Educational requirements
Readability	10%	Structure and clarity

Grade Scale

• A (90-100): Excellent ATS compatibility
• B (80-89): Good, minor improvements needed
• C (70-79): Fair, several improvements needed
• D (60-69): Poor, major improvements required
• F (0-59): Very poor, significant overhaul needed

---

🚀 Performance Tips

For Better AI Recommendations

1. Use Detailed Level: Get comprehensive analysis with examples
2. Provide Complete Job Descriptions: More context = better recommendations
3. Enable Verbose Mode: Get insights into the analysis process

For Batch Processing

1. Use Concise Level: Faster processing for multiple resumes
2. Enable Parallel Processing: Use --parallel for faster execution
3. Optimize Workers: Set --workers based on your system specs

For Production Use

1. Set API Limits: Configure rate limiting for AI providers
2. Monitor Usage: Track API costs and usage patterns
3. Cache Results: Implement caching for repeated analyses

---

🔍 Troubleshooting

Common Issues

AI Features Not Working

# Check API key
echo $ATS_LLM_API_KEY

# Test API connection
curl -H "Authorization: Bearer $ATS_LLM_API_KEY" \
  https://api.openai.com/v1/models

# Enable debug logging
ATS_LLM_ENABLED=true LOG_LEVEL=DEBUG ats-score --resume resume.pdf --jd job.txt

Installation Issues

# Install missing dependencies
pip install --upgrade ats-resume-scorer
python -m spacy download en_core_web_sm

# For M1 Macs
pip install --upgrade pip setuptools wheel
pip install ats-resume-scorer --no-cache-dir

File Processing Errors

# Check file format
file resume.pdf

# Test with simple text file
echo "John Doe, Software Engineer" > test_resume.txt
ats-score --resume test_resume.txt --jd job.txt

# Check file permissions
ls -la resume.pdf

Memory Issues (Large Batches)

# Reduce batch size
python cli_advanced.py batch --resume-dir ./resumes --jd job.txt --workers 2

# Use concise level
python cli_advanced.py batch --resume-dir ./resumes --jd job.txt --level concise

# Monitor memory usage
docker stats  # if using Docker

---

🆕 What's New in v2.0

AI-Powered Recommendations

• Context-Aware Suggestions: AI understands your specific job requirements
• Actionable Guidance: Step-by-step improvement plans
• Industry-Specific Advice: Tailored recommendations for different roles

Enhanced User Experience

• Modern Web Interface: Responsive design with real-time feedback
• Multiple Detail Levels: Choose the right amount of detail for your needs
• Batch Processing: Efficiently process multiple resumes

Developer Features

• Flexible LLM Integration: Support for multiple AI providers
• Enhanced API: RESTful endpoints with comprehensive documentation
• Docker Support: Complete containerization with monitoring

---

🛣️ Roadmap

Upcoming Features

• Resume Builder Integration: Generate optimized resumes based on job descriptions
• Industry Templates: Pre-configured settings for different industries
• Advanced Analytics: Historical tracking and improvement metrics
• Integration APIs: Connect with popular HR platforms

AI Enhancements

• Multi-Language Support: Recommendations in multiple languages
• Visual Analysis: AI-powered formatting and design suggestions
• Competitive Analysis: Compare against industry benchmarks

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch
3. Add your enhancements
4. Test thoroughly (including AI features)
5. Submit a pull request

Development Setup

# Clone and setup
git clone https://github.com/yourusername/ats-resume-scorer.git
cd ats-resume-scorer

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Test AI features (requires API key)
export ATS_LLM_API_KEY=your-test-key
pytest tests/test_llm_integration.py

---

📄 License

MIT License - see LICENSE file for details.

---

🆘 Support

Get Help

• 📚 Documentation: Check this README and code comments
• 🐛 Issues: Create GitHub issue with logs and reproduction steps
• 💬 Discussions: Join GitHub Discussions for community help

Professional Support

For enterprise support, custom integrations, or consulting services, contact us at [[e-mail]].

---

⭐ Show Your Support

If this project helps you land your dream job, please:

• ⭐ Star the repository
• 🐛 Report issues and suggest improvements
• 🤝 Contribute code or documentation
• 📢 Share with others who might benefit

---

🎯 Start optimizing resumes with AI today!

pip install ats-resume-scorer
export ATS_LLM_API_KEY=your-key
ats-score --resume your_resume.pdf --jd job_description.txt --level detailed --enable-llm