Skip to content

ATS Scorer Quick Start

This guide will help you get started with the ATS Scorer package.

Installation

Basic Installation

For BasicScorer (no ML dependencies):

uv pip install at-scorer

With ML Support

For ProScorer with ML capabilities:

uv pip install "at-scorer[ml]"

Additional Requirements

If using ProScorer, you'll also need to install spaCy language model:

python -m spacy download en_core_web_sm

Basic Usage

Using BasicScorer

from at_scorer import BasicScorer, ResumeData, JobDescriptionText

# Initialize scorer
scorer = BasicScorer()

# Create resume data
resume = ResumeData(
    executive_summary="Experienced software engineer with 5+ years...",
    skills=["Python", "FastAPI", "PostgreSQL", "Docker"],
    work_experience=[
        WorkExperienceEntry(
            role="Senior Software Engineer",
            company="Tech Corp",
            duration="3 years",
            achievements=["Led team of 5 developers", "Improved performance by 40%"]
        )
    ],
    education=[
        EducationEntry(
            degree="BS Computer Science",
            institution="State University"
        )
    ]
)

# Create job description
job = JobDescriptionText(
    text="We are looking for a Senior Python Developer...",
    keywords=["Python", "FastAPI", "PostgreSQL", "Docker", "Kubernetes"]
)

# Score the resume
result = scorer.score(resume, job)

# View results
print(f"Overall Score: {result.overall_score}/100")
print(f"Keyword Score: {result.breakdown.keyword_score:.1f}")
print(f"Skills Score: {result.breakdown.skills_score:.1f}")

# Check matched items
print(f"Matched Keywords: {result.matched_keywords}")
print(f"Matched Skills: {result.matched_skills}")

# Review recommendations
for rec in result.recommendations:
    print(f"\n{rec.priority.upper()}: {rec.message}")
    print(f"  Items: {rec.actionable_items}")

Using ProScorer

from at_scorer import ProScorer, ResumeData, JobDescriptionStructured
from at_scorer.ml import MLConfig

# Optional: Customize ML configuration
config = MLConfig(
    embedding_model="all-mpnet-base-v2",  # Better quality, slower
    similarity_threshold=0.75,
    use_gpu=True,
    cache_embeddings=True
)

# Initialize scorer with custom config
scorer = ProScorer(ml_config=config)

# Or use default config
scorer = ProScorer()

# Create structured job description
job = JobDescriptionStructured(
    title="Senior Python Developer",
    required_skills=["Python", "FastAPI", "PostgreSQL"],
    preferred_skills=["Docker", "Kubernetes", "AWS"],
    required_experience_years=5.0,
    required_education="Bachelor's degree in Computer Science",
    required_certifications=["AWS Certified Solutions Architect"],
    location="San Francisco, CA",
    description="We are looking for an experienced Python developer...",
    keywords=["Python", "FastAPI", "microservices", "REST API"]
)

# Score the resume (same resume as above)
result = scorer.score(resume, job)

# View comprehensive results
print(f"Overall Score: {result.overall_score}/100")
print("\nScore Breakdown:")
print(f"  Keywords: {result.breakdown.keyword_score:.1f}")
print(f"  Skills: {result.breakdown.skills_score:.1f}")
print(f"  Experience: {result.breakdown.experience_score:.1f}")
print(f"  Education: {result.breakdown.education_score:.1f}")
print(f"  Certifications: {result.breakdown.certification_score:.1f}")
print(f"  Location: {result.breakdown.location_score:.1f}")
print(f"  Job Title: {result.breakdown.job_title_score:.1f}")
print(f"  Achievements: {result.breakdown.achievements_score:.1f}")
print(f"  Summary: {result.breakdown.summary_score:.1f}")

# Review recommendations
for rec in result.recommendations:
    print(f"\n{rec.category.upper()} ({rec.priority}):")
    print(f"  {rec.message}")
    print(f"  Action items: {rec.actionable_items}")

Data Models

ResumeData

The ResumeData model represents structured resume information:

from at_scorer import ResumeData, ContactInformation, WorkExperienceEntry

resume = ResumeData(
    executive_summary="Professional summary...",
    skills=["Skill1", "Skill2"],
    contact_information=ContactInformation(
        name="John Doe",
        email="john@example.com",
        location=ContactLocation(
            city="San Francisco",
            state="CA",
            country="USA"
        )
    ),
    work_experience=[
        WorkExperienceEntry(
            role="Software Engineer",
            company="Company Name",
            duration="2 years",
            achievements=["Achievement 1", "Achievement 2"]
        )
    ],
    # ... more fields
)

JobDescription

You can use either text-based or structured job descriptions:

# Text-based (simpler)
from at_scorer import JobDescriptionText

job = JobDescriptionText(
    text="Full job description text...",
    keywords=["keyword1", "keyword2"]  # Optional
)

# Structured (more accurate)
from at_scorer import JobDescriptionStructured

job = JobDescriptionStructured(
    title="Job Title",
    required_skills=["Skill1", "Skill2"],
    preferred_skills=["Skill3"],
    required_experience_years=3.0,
    # ... more fields
)

Advanced Configuration

ML Configuration

Customize ProScorer behavior:

from at_scorer.ml import MLConfig

config = MLConfig(
    embedding_model="all-mpnet-base-v2",  # Options: all-MiniLM-L6-v2, all-mpnet-base-v2
    spacy_model="en_core_web_sm",  # spaCy model for text analysis
    similarity_threshold=0.75,  # Minimum similarity for matches
    use_gpu=True,  # Use GPU if available
    cache_embeddings=True,  # Cache computed embeddings
    batch_size=32  # Batch size for processing
)

scorer = ProScorer(ml_config=config)

Best Practices

  1. Use structured job descriptions when possible for better accuracy
  2. Provide complete resume data including all sections
  3. Use ProScorer for production applications requiring semantic understanding
  4. Use BasicScorer for quick evaluations or when ML dependencies aren't available
  5. Review recommendations to understand score gaps
  6. Cache scorer instances when processing multiple resumes

Troubleshooting

Import Errors

If you see import errors for sentence-transformers:

uv pip install "at-scorer[ml]"

spaCy Model Not Found

Download the required spaCy model:

python -m spacy download en_core_web_sm

GPU Not Available

ProScorer will automatically fall back to CPU if GPU is not available. To force CPU:

config = MLConfig(use_gpu=False)
scorer = ProScorer(ml_config=config)

Next Steps