Analyzes how well your resume matches a job posting with an AI-optional fit score. Optionally tailors your resume bullets and cover letter to the specific job.
No API key required to get started. Fit score works completely offline.
- Overview
- Features
- Prerequisites
- Installation
- Configuration
- Usage
- API Providers
- System Diagrams ⭐ Start here for visual understanding
- How It Works
- Project Structure
- Documentation
- Roadmap
- Contributing
- License
- Contact
Resume Tailor is a Python tool that helps job seekers tailor their applications with:
-
Fit Score (0-100) — How well your resume matches the job posting
- Transparent, explainable algorithm (no black box)
- Weighted by keyword frequency, requirement level, and synonyms
- Shows which skills match and which are missing
- Works completely offline, no API needed
-
AI-Tailored Content (optional) — Personalized resume bullets and cover letter
- Rewrites your bullets to highlight relevant experience
- Generates a natural, personalized cover letter
- Only uses skills/experience actually in your resume
- Choose from 3 AI providers (Groq, Gemini, OpenAI)
Fit Score: 72.0%
Matching Skills:
- python
- sql
- react
- agile
Missing Skills:
- kubernetes
- aws
- docker
- leadership
✅ Deterministic Fit Score
- No machine learning, fully explainable
- Weighted by keyword frequency and requirement level
- Understands skill synonyms (JS = JavaScript, SQL = Database)
- Transparent matching/missing skill lists
✅ AI-Powered Tailoring (optional)
- Rewrites resume bullets for specific job
- Generates personalized cover letters
- Honesty rule: only uses real experience from your resume
- Supports 3 AI providers with different quality/cost tradeoffs
✅ Two Interfaces
- CLI — Fast, scriptable, batch processing
- Web UI — Interactive Streamlit app with session history
✅ Well-Tested & Documented
- 20 tests, all passing (no API key required)
- Comprehensive documentation with examples
- Clear roadmap for future improvements
- Design decisions documented in reflection.md
✅ Flexible AI Provider Support
- Groq (free, ultra-fast)
- Google Gemini (free tier)
- OpenAI (paid, best quality)
- Easy to switch providers via environment variable
- Python: 3.10 or higher
- pip: Python package manager
- Virtual Environment: Recommended (venv or conda)
- API Key: Optional (only needed for AI tailoring)
git clone https://github.com/yourusername/resume-tailor.git
cd resume-tailor# On Mac/Linux
python3 -m venv .venv
source .venv/bin/activate
# On Windows (Command Prompt)
python -m venv .venv
.venv\Scripts\activate
# On Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1pip install -r requirements.txtcp .env.example .env
# Edit .env and add your API key(s) - see Configuration section belowNo configuration needed. Just run:
python main.py your_resume.txt job_posting.txt-
Copy environment template:
cp .env.example .env
-
Choose ONE provider and add your API key:
Option A: Groq (Recommended - free, ultra-fast)
AI_PROVIDER=groq GROQ_API_KEY=your_key_here
Get free key at: https://console.groq.com
Option B: Google Gemini (Free tier available)
AI_PROVIDER=gemini GEMINI_API_KEY=your_key_here
Get free key at: https://aistudio.google.com
Option C: OpenAI (Paid with trial credits)
AI_PROVIDER=openai OPENAI_API_KEY=your_key_here
Get key at: https://platform.openai.com/api-keys
-
Test configuration:
python main.py examples/resume.txt examples/job.txt both
# Basic usage - fit score only
python main.py <resume_file> <job_file> [mode]
# Modes:
python main.py resume.txt job.txt # Fit score only
python main.py resume.txt job.txt bullets # Fit score + resume bullets
python main.py resume.txt job.txt cover_letter # Fit score + cover letter
python main.py resume.txt job.txt both # Fit score + bullets + cover letterstreamlit run app.pyThen open: http://localhost:8501
Features:
- Text areas for resume and job posting
- Real-time fit score calculation
- AI-generated bullets and cover letter
- Session history maintained during session
# Try the included examples (no API key needed)
python main.py examples/resume.txt examples/job.txt
# Output:
# Fit score: 72.0
# Matching: ['python', 'sql', 'react']
# Missing: ['kubernetes', 'aws', 'docker']Choose the provider that fits your needs:
| Feature | Groq | Gemini | OpenAI |
|---|---|---|---|
| Model | Mixtral 8x7B | gemini-2.5-flash | gpt-4o-mini |
| Speed | ⚡ Ultra-fast | Fast | Fast |
| Cost | Free | Free tier | Paid (trials) |
| Quality | Good | Excellent | Excellent |
| Best For | Speed, free tier | Quality, free | Best quality |
| Sign Up | https://console.groq.com | https://aistudio.google.com | https://platform.openai.com/api-keys |
All providers are optional. Fit score works without any API key.
Visual explanations of how the system works. Start here if you're new.
| Diagram | Best For | View |
|---|---|---|
| UML Class Diagram | Code structure, classes, relationships | diagrams/uml_final.mmd |
| System Architecture | Complete flow, data pipelines | diagrams/architecture.mmd |
| Data Flow | Algorithm details, transformations | diagrams/dataflow.mmd |
View online: Paste any .mmd file content into https://mermaid.live
VS Code: Install "Mermaid Editor" extension, right-click .mmd file → Open Preview
What each diagram shows:
- UML: All classes, 7 helper functions, 3 AI providers, design philosophy
- Architecture: Input → CLI/Web → Core pipeline → AI providers → Output
- Data Flow: Keyword extraction → Weighting → Scoring → AI (optional) → Display
Which diagram answers your question?
- "How does the code work?" → UML
- "What's the overall system?" → Architecture
- "How is the fit score calculated?" → Data Flow
- "What's optional vs required?" → Architecture + Data Flow
See SPECS.md for technical details beyond diagrams.
# Using provided test runner (no pytest needed)
python tests/test_resume_tailor.py
# Or with pytest (if installed)
pytest tests/ -vSUCCESS: ALL 20 TESTS PASSED
Category Breakdown:
├─ Word Extraction & Processing (4 tests)
│ ├─ extract_words filtering
│ ├─ resume keywords extraction
│ ├─ job keyword ranking
│ └─ synonym normalization
│
├─ Fit Score — Synonyms (2 tests)
│ ├─ fit score finds matching skills
│ └─ fit score recognizes synonyms
│
├─ Fit Score — Weighted & Required/Preferred (7 tests)
│ ├─ zero score on no matches
│ ├─ empty job posting handling
│ ├─ frequency weighting
│ ├─ required keyword detection
│ ├─ preferred keyword detection
│ ├─ requirement weight defaults
│ └─ required vs. preferred weighting
│
└─ Prompt & AI Integration (7 tests)
├─ task instruction modes
├─ honesty rule inclusion
├─ tailor output assembly
├─ Gemini API error handling
├─ Groq API error handling
├─ OpenAI API error handling
└─ provider selection
No API key required for any test. AI calls are mocked.
See System Diagrams section above for detailed visual explanations. Quick summary:
-
Fit Score (offline, always works)
- Extract job keywords (top 20, normalized, filtered)
- Weight by frequency + requirement level
- Compare against resume keywords
- Return: score 0-100, matching skills, missing skills
-
AI Tailoring (optional, requires API key)
- Build prompt: resume + job + honesty rule
- Send to Groq/Gemini/OpenAI
- Return: generated bullets or cover letter
The Data Flow diagram shows the exact transformations at each stage with a worked example. The Architecture diagram shows how all components fit together.
resume_tailor/
├── README.md ← You are here
├── SPECS.md ← Technical specifications
├── ROADMAP.md ← Future improvements
├── reflection.md ← Design decisions & tradeoffs
├── requirements.txt ← Python dependencies
├── .env.example ← Environment template
├── .gitignore ← Git ignore rules
│
├── resume_tailor_system.py ← Core engine (no UI)
├── formatting.py ← Display formatting
├── main.py ← CLI interface
├── app.py ← Streamlit web interface
│
├── tests/
│ └── test_resume_tailor.py ← 20 tests (all passing)
│
├── examples/
│ ├── resume.txt ← Sample resume
│ └── job.txt ← Sample job posting
│
└── diagrams/
├── uml_final.mmd ← Code structure (classes, relationships)
├── architecture.mmd ← System flow (input → output)
└── dataflow.mmd ← Data transformations (algorithm details)
| Document | Purpose | Best For |
|---|---|---|
| SPECS.md | Technical details (architecture, algorithms, dependencies, testing) | Understanding implementation, adding features |
| reflection.md | Design decisions, tradeoffs, confidence level | Understanding "why", learning from decisions |
| ROADMAP.md | Future improvements (Levels 2-5), implementation guide | Planning next features |
| requirements.txt | All dependencies organized by purpose | Managing Python environment |
| .env.example | Environment variable template | Configuring API keys |
- Level 0: Foundation (fit score + AI, 20 tests, two interfaces)
- Level 1: Sharper Signal (weighted scoring, synonym awareness, required/preferred detection)
Level 2: Real Data
- PDF resume parsing
Level 3: Prove It Works
- Hand-label resume/job pairs
- Measure algorithm accuracy
- Write evaluation results
Level 4: Better Algorithms
- Pick ONE: semantic similarity / job classification / experience matching
Level 5: Multi-Model Comparison
- Compare Groq vs. Gemini vs. OpenAI output
- Document differences honestly
See ROADMAP.md for details.
This project is built to showcase portfolio-quality code. If you'd like to contribute:
- Review ROADMAP.md for planned improvements
- Check SPECS.md for architecture and test patterns
- Add tests for any new feature (see
tests/test_resume_tailor.py) - Document decisions in
reflection.md - Keep it simple — no premature optimization or over-engineering
- All changes must include tests
- All tests must pass (
python tests/test_resume_tailor.py) - Document WHY in reflection.md, not just WHAT
- No dependencies without discussion (see requirements.txt)
MIT License - See LICENSE file for details.
This project is free to use, modify, and distribute.
- Author: Irakli Eradze
- Email: iraklieradzeg@gmail.com
- GitHub: Resume Tailor
- Python community for excellent tools and libraries
- Groq, Google, and OpenAI for free/affordable API access
- Streamlit for making web UIs simple
- The job search community for inspiration
Q: Do I need an API key to use this? A: No. The fit score works completely offline. API keys are optional for AI tailoring.
Q: Which AI provider should I choose? A: Groq (free, fast) for getting started. OpenAI if you want best quality.
Q: Can I use this for multiple resumes/jobs? A: Yes. CLI is perfect for batch processing multiple pairs.
Q: How accurate is the fit score? A: It's literal word matching, which is transparent but not semantic. See reflection.md for limitations.
Q: Is my data shared with the AI providers? A: Only if you use AI features and configure API keys. Your resume is sent to the provider you choose.
Q: Can I modify the algorithm?
A: Yes. The algorithm is in resume_tailor_system.py. See test patterns in tests/test_resume_tailor.py.
Last Updated: August 2026 Status: Production Ready - Level 0 & 1 Complete