🚀 ResumeTool - AI-Powered Job Matching & Resume Optimization

Transform your job search with AI-powered resume analysis, intelligent job matching, and automated opportunity discovery.

ResumeTool is a comprehensive job search assistant that combines advanced resume parsing, AI-powered analysis, and multi-source job discovery to help professionals find their ideal career opportunities faster and more effectively.

✨ Key Features

🧠 Intelligent Resume Analysis

6x Better Skill Detection with AI enhancement
Professional Title Generation from experience
Comprehensive Skill Categorization with expertise levels
Multi-Format Support (PDF, DOCX, TXT)

🎯 Smart Job Matching

AI-Powered Compatibility Scoring (up to 85% accuracy)
Multi-Source Job Discovery (Indeed, ZipRecruiter + more)
Automated Skill Gap Analysis with improvement recommendations
Remote-First Job Options with location flexibility

⚡ Lightning-Fast Workflow

One-Command Analysis: ./run.sh analyze resume.pdf
Interactive Wizard Mode for guided job search
Rich CLI Interface with beautiful tables and progress bars
Cost-Effective AI using GPT-5-nano

🏢 Hiring Triage System (employer-side)

The real problem in modern hiring isn't finding applicants — it's what happens after. An ATS surfaces 180 "qualified" candidates from 500 submissions. A hiring team of 3 cannot meaningfully evaluate 180 people. So most of those candidates get ghosted, not because they failed, but because there was no intelligent routing layer after the initial filter.

This system is that routing layer. It picks up where the ATS leaves off and applies a multi-stage evaluation that goes far beyond keyword matching — looking at how a candidate thinks, how much effort they actually put in, and who they are beyond their resume.

The Problem This Solves

500 applicants submitted
    ↓  ATS / initial AI filter
180 "qualified" matches  ←── this is where hiring teams get stuck
    ↓  THIS TOOL
~15–20 candidates worth a real human conversation

Pipeline Overview

Stage	What it does	Status
1. Rubric scoring	Scores resumes against weighted, named criteria — not keyword matching. HR defines dimensions like "years of relevant experience" with good/bad examples.	✅ Built
2. AI-conducted interview	Candidates receive a text-based async interview. Questions are psychologically layered — similar themes asked in different ways across the session to check for consistency and depth, not just surface answers.	✅ Built (text), voice planned
3. Effort & intent scoring	Did this person just blast their resume and disappear? Or did they follow up, research the company, customize their cover letter? Two candidates with identical resumes should not score the same if one went the extra mile.	✅ Built
4. Public footprint analysis	Looks at who the candidate is beyond the resume — LinkedIn activity, GitHub contributions, published work, public professional presence. Signals genuine expertise and engagement vs. a polished document with little behind it.	🚧 Planned
5. OSINT pre-screen	Using only publicly available information, runs a background pre-check: news mentions, court records, professional history verification. Flags items for HR review rather than auto-rejecting — the human makes the final call.	🚧 Planned
6. Auto-routing	Every candidate gets a tier (A/B/C/D) and a response. Tier A gets a fast-track interview invite. Tier D gets a warm, human decline. No one gets silence.	✅ Built
7. Feedback loop	Hiring manager decisions feed back into the model. After 10+ decisions, the system learns what "good" actually means for this specific company and calibrates accordingly.	✅ Built

What "Effort Scoring" Actually Means

Two candidates submit identical resumes for the same role. Candidate A applied via LinkedIn in 30 seconds. Candidate B applied directly, wrote a cover letter that referenced a specific product feature, emailed a follow-up two days later, and mentioned something from the company blog.

Most ATS systems treat these as equal. This system does not.

Signals tracked:

Application quality — cover letter analyzed for genuine customization vs. generic template (AI-scored)
Time-to-apply — early applicants signal higher intent; normalized against posting date
Source channel — referral > direct apply > job board blast
Follow-up behavior — proactive contact after applying is logged and weighted
Research indicators — references to specific company details, products, team members, or recent news in written responses

What "AI Interview" Actually Means

This is not a quiz. The async text interview uses psychological interview design:

Questions are generated from rubric gaps — if a candidate scored low on "system design," they get probed there specifically
Similar themes are asked in different framings across the session to test consistency (a common technique in structured interviewing to detect coached or fabricated answers)
Behavioral ("tell me about a time..."), situational ("how would you handle..."), and verification ("walk me through how you built...") question types are mixed
Answers are scored on specificity, depth, and internal consistency — not just keyword presence

Public Footprint & OSINT (Planned)

Important note on fairness: These signals are surfaced as information for a human reviewer, not as automatic disqualifiers. The goal is to give hiring teams more signal, not to automate decisions that could introduce bias. Companies using these features should establish clear, consistent policies for how the information is reviewed.

Planned data sources (public only):

LinkedIn — activity level, recommendations, publication history, network density in relevant fields
GitHub / GitLab — actual code contributions, commit frequency, open source engagement
Google / news — professional mentions, published articles, conference talks, press coverage
Public records — court records, business filings, professional license status
Domain expertise signals — Stack Overflow reputation, industry forum participation, published research

The output is a public profile summary with flagged items for HR review. Nothing is used to auto-reject.

Running the HR Dashboard

# Set your OpenAI key and start the server
export RESUMETOOL_OPENAI_API_KEY="sk-..."
uvicorn resumetool.server.app:app --reload

# Open http://localhost:8000  (default login: admin / changeme)
# Change credentials via env var:
export RESUMETOOL_HR_AUTH_USERS="yourname:yourpassword"

Submitting Applications via API

# Ingest a single resume — triage runs immediately and returns a tier
curl -u admin:changeme -X POST http://localhost:8000/api/v1/applications \
  -F "req_id=<job-req-id>" \
  -F "candidate_email=alice@example.com" \
  -F "candidate_name=Alice Smith" \
  -F "source=linkedin" \
  -F "days_since_posting=2" \
  -F "cover_letter=I've followed your work on X for two years and..." \
  -F "resume_file=@alice_resume.pdf"
# Returns: {"tier": "A", "composite_score": 0.88, "screen_link": "/screen/<token>"}

Creating a Job Requisition with a Rubric

import httpx

req = httpx.post("http://localhost:8000/api/v1/jobs", auth=("admin", "changeme"), json={
    "company_id": "acme-corp",
    "title": "Senior Backend Engineer",
    "description": "We're looking for...",
    "rubric": {
        "criteria": [
            {"name": "Python depth", "description": "3+ years production Python", "weight": 0.40,
             "examples_good": ["Built async APIs with FastAPI at scale"],
             "examples_bad": ["Used Python for scripting only"]},
            {"name": "System design", "description": "Distributed systems experience", "weight": 0.35},
            {"name": "Team leadership", "description": "Led 2+ engineers", "weight": 0.25},
        ]
    }
})
print(req.json()["id"])  # use this req_id when submitting applications

Key Functions (Built)

Function	Location	Purpose
`score_resume_against_rubric()`	`triage/scoring.py`	Stage 1 — per-criterion AI scoring with company calibration
`generate_screening_questions()`	`triage/screening.py`	Stage 2 — generates psychologically layered questions from rubric gaps
`score_screening_answers()`	`triage/screening.py`	Stage 2 — scores answers on specificity, depth, and consistency
`compute_behavioral_score()`	`triage/behavioral.py`	Stage 3 — effort and intent composite from multiple signals
`compute_composite()`	`triage/router.py`	Stage 6 — weighted score across all active stages
`assign_tier()`	`triage/router.py`	Stage 6 — A/B/C/D tier assignment
`generate_response_email()`	`triage/router.py`	Stage 6 — tier-specific human-sounding response email
`run_triage()`	`triage/pipeline.py`	Orchestrates all stages for one application
`record_decision()`	`feedback/loop.py`	Stage 7 — stores HM decision and triggers prompt calibration

Tier Logic

Composite = 50% rubric score + 35% interview score + 15% effort/intent score
(interview weight rolls into rubric until the candidate completes their screen)

Tier A  ≥ 85%  →  Fast-track interview invite
Tier B  65-85% →  Active hold — HM reviews with full context
Tier C  45-65% →  Polite decline with 1-2 specific gap notes
Tier D  < 45%  →  Warm decline

No candidate gets silence. Every application generates a response.

🎬 Quick Demo

# Analyze your resume with AI
./run.sh analyze resume.pdf --enhance

# Find matching jobs automatically  
./run.sh match resume.pdf --query "cloud engineer" --remote

# Interactive guided mode
./run.sh wizard

Sample Output:

╭─────────────────────────────────────────────────────────────────╮
│ Resume Analysis: resume.pdf                                     │
╰─────────────────────────────────────────────────────────────────╯
Title: Senior Cloud Architect
Email: candidate@example.com

                    Skills                     
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Skill        ┃ Level        ┃ Category   ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ AWS          │ expert       │ Cloud      │
│ Kubernetes   │ advanced     │ DevOps     │
│ Python       │ expert       │ Programming│
│ Leadership   │ intermediate │ Management │
└──────────────┴──────────────┴────────────┘

🎯 Top Job Match: Senior Cloud Engineer (92% compatibility)
✅ Matching Skills: AWS, Kubernetes, Python, Docker
💡 Recommendation: Consider AWS Solutions Architect certification

🚀 Getting Started

Prerequisites

Python 3.11+
Virtual environment support
Optional: OpenAI API key for enhanced AI features

Installation

# Clone the repository
git clone https://github.com/yourusername/resumetool.git
cd resumetool

# Set up virtual environment
source .venv/bin/activate
export PYTHONPATH=src

# Quick start with convenience script
./run.sh wizard

Basic Usage

# Analyze resume (basic)
./run.sh analyze my_resume.pdf

# With AI enhancement (requires OpenAI key)
export OPENAI_API_KEY="your_key_here"
./run.sh analyze my_resume.pdf --enhance

# Discover job opportunities
./run.sh discover "data scientist" --remote --limit 10

# Find personalized job matches
./run.sh match my_resume.pdf --query "machine learning engineer"

📊 Performance Comparison

Feature	Without AI	With AI Enhancement
Skills Detected	1-3 basic	6-15 categorized
Experience Parsing	50% accuracy	95% accuracy
Job Match Quality	Generic 50%	Intelligent 85%+
Professional Insights	None	Title + recommendations
Overall Improvement	Baseline	6x Better Results

🛠 Advanced Features

Command Line Interface

resumetool [OPTIONS] COMMAND [ARGS]...

Commands:
  analyze     Parse and analyze resume files
  discover    Find job opportunities  
  match       Get personalized job matches
  optimize    Generate tailored resume versions (coming soon)
  apply       Track applications (coming soon)
  wizard      Interactive guided mode

Python API

from resumetool.analysis.resume_parser import ResumeParser
from resumetool.ai.openai_client import OpenAIAnalyzer

# Parse resume
parser = ResumeParser()
analysis = parser.parse_file("resume.pdf")

# Enhance with AI
analyzer = OpenAIAnalyzer(api_key="your_key")
enhanced = analyzer.enhance_resume_analysis(analysis)

print(f"Found {len(enhanced.skills)} skills")

🎯 Use Cases

For Job Seekers

Career Transition: Understand how your skills translate to new roles
Skill Gap Analysis: Identify what to learn for target positions
Market Research: Discover in-demand skills in your field
Application Optimization: Tailor applications to specific roles

For Recruiters & HR

Candidate Screening: Quick skill assessment and role matching
Market Analysis: Understand skill trends and compensation
Job Description Optimization: Improve posting effectiveness

For Career Coaches

Client Assessment: Comprehensive skill and experience analysis
Career Planning: Data-driven career path recommendations
Progress Tracking: Monitor skill development over time

🔮 Roadmap

✅ Phase 1: Core Analysis (Complete)

Resume parsing with AI enhancement
Multi-source job discovery
Intelligent job matching

✅ Phase 2: Triage Foundation (Complete)

Rubric-based structured resume scoring (not keyword matching)
Async text interview with AI-generated, psychologically layered questions
Effort and intent scoring (cover letter quality, time-to-apply, follow-up, source channel)
Auto-routing with tiered responses — no candidate gets silence
Per-company feedback loop via prompt calibration
HR web dashboard

🚧 Phase 3: Deeper Candidate Intelligence (Next)

Public footprint analysis — LinkedIn activity, GitHub contributions, published work, professional presence
OSINT pre-screen — public records, news mentions, professional license verification; surfaced for HR review, not auto-rejection
Voice screening option — async audio responses with Whisper transcription, adds tone and fluency signal to text answers
Consistency scoring — detect coached or fabricated answers by cross-referencing responses across multi-part interview questions
Email delivery — Resend/SendGrid integration so response emails actually send, not just generate

📋 Phase 4: Scale & Integrations (Planned)

Celery + Redis background processing for high-volume ingestion (500+ resumes in a batch)
ATS integrations — push/pull with Greenhouse, Lever, Workday
Bulk resume upload — ingest a ZIP of ATS-exported resumes in one API call
Candidate portal — let candidates check their screen status and respond to follow-up questions
Audit log — exportable record of every scoring decision for compliance review

🏗 Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
│   Resume Input  │───▶│   AI Analysis    │───▶│   Job Discovery     │
│  (PDF/DOCX/TXT) │    │  (GPT-5-nano)    │    │ (Multiple Sources)  │
└─────────────────┘    └──────────────────┘    └─────────────────────┘
                                │                         │
                                ▼                         ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
│  Career Advice  │◀───│ Intelligent      │◀───│   Match Scoring     │
│ & Optimization  │    │ Recommendations  │    │   & Analysis        │
└─────────────────┘    └──────────────────┘    └─────────────────────┘

📈 Success Stories

"ResumeTool helped me identify 5 additional skills from my experience that I wasn't highlighting. Got 3 interviews in the first week!"
— Software Engineer, Career Transition

"The AI matching found roles I never would have considered. 85% match score led to my dream job at a startup."
— Product Manager, Job Search Success

"As a recruiter, this tool saves me hours of manual resume screening. The skill categorization is incredibly accurate."
— Senior Recruiter, Hiring Efficiency

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Code formatting
ruff check .

📄 Documentation

User Guide - Complete usage instructions
Demo Results - Detailed feature showcase
Quick Start - Get up and running fast

🌐 Deploy the marketing site to GitHub Pages

The marketing site (/ landing + /demo guided walkthrough) is fully static and ships via .github/workflows/pages.yml on every push to main. The portal is not included — it requires a live FastAPI deployment with a database.

# Build locally to /dist
python scripts/build_static.py

# Build to a custom directory and base path
python scripts/build_static.py --out public --base /resumetool/

The script:

Renders landing.html and demo.html from the Jinja2 templates
Injects <base href="/resumetool/"> so absolute paths resolve under the GitHub Pages project URL
Rewrites every /dashboard link to /#contact (so the "Open Portal" CTAs route to the contact section on the marketing page instead of 404'ing on Pages)
Copies static/*.css and writes a .nojekyll marker

After pushing to GitHub, enable Pages → "GitHub Actions" and the site will be live at https://<user>.github.io/resumetool/.

🔒 Privacy & Security

Local Processing: Resume analysis happens on your machine
Optional AI: Choose when to send data to OpenAI
No Data Storage: We don't store your personal information
Open Source: Full transparency in code and processing

💬 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Complete guides included in repository

📜 License

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

Made with ❤️ for job seekers everywhere

User Guide • Demo • Quick Start

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.github/workflows		.github/workflows
scripts		scripts
src/resumetool		src/resumetool
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
AI_START.md		AI_START.md
DEMO_RESULTS.md		DEMO_RESULTS.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
USAGE_QUICK.md		USAGE_QUICK.md
USER_GUIDE.md		USER_GUIDE.md
plan.md		plan.md
pyproject.toml		pyproject.toml
run.sh		run.sh

Folders and files

Latest commit

History

Repository files navigation

🚀 ResumeTool - AI-Powered Job Matching & Resume Optimization

✨ Key Features

🧠 Intelligent Resume Analysis

🎯 Smart Job Matching

⚡ Lightning-Fast Workflow

🏢 Hiring Triage System (employer-side)

The Problem This Solves

Pipeline Overview

What "Effort Scoring" Actually Means

What "AI Interview" Actually Means

Public Footprint & OSINT (Planned)

Running the HR Dashboard

Submitting Applications via API

Creating a Job Requisition with a Rubric

Key Functions (Built)

Tier Logic

🎬 Quick Demo

🚀 Getting Started

Prerequisites

Installation

Basic Usage

📊 Performance Comparison

🛠 Advanced Features

Command Line Interface

Python API

🎯 Use Cases

For Job Seekers

For Recruiters & HR

For Career Coaches

🔮 Roadmap

✅ Phase 1: Core Analysis (Complete)

✅ Phase 2: Triage Foundation (Complete)

🚧 Phase 3: Deeper Candidate Intelligence (Next)

📋 Phase 4: Scale & Integrations (Planned)

🏗 Architecture

📈 Success Stories

🤝 Contributing

Development Setup

📄 Documentation

🌐 Deploy the marketing site to GitHub Pages

🔒 Privacy & Security

💬 Support

📜 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages