Abstract

ResumeLens is an AI-powered resume analysis system designed to help candidates understand how well their resume aligns with a target role and what they should improve next. The platform accepts resume content as raw text or uploaded files, optionally accepts a job description as text or URL, and generates a structured candidate profile, gap analysis, rewritten resume bullets, ATS keyword recommendations, interview questions, and an action plan.

The system is built with a FastAPI backend, LangGraph-based multi-step orchestration, PostgreSQL persistence, and a Streamlit interface for interactive usage. Rather than behaving like a one-shot prompt wrapper, ResumeLens is designed as a practical AI application with authentication, report history, preference memory, structured outputs, and production-oriented backend patterns.

Its main value is not simply producing AI-generated text, but turning resume improvement into a repeatable, explainable workflow. ResumeLens gives users both diagnosis and action: what is strong, what is missing, what should be rewritten, and how to become a better fit for a given role.

Dataset

ResumeLens is not trained on a custom large-scale labeled dataset in the traditional machine learning sense. Instead, it operates on user-provided runtime inputs plus structured intermediate artifacts generated during analysis.

Primary input data sources

• Resume text pasted directly into the interface
• Uploaded resume files:
  • .txt
  • .pdf
  • .docx
• Optional job description input:
  • pasted text
  • public job posting URL

Derived internal artifacts

From the input data, the system generates:

• normalized resume text
• normalized job description text
• structured candidate profile
• gap analysis report
• final improvement report
• stored user preferences
• analysis history for historical comparison

Data characteristics

The data is semi-structured and user-specific. Typical resume content includes:

• candidate name
• education
• skills
• projects
• experience summary
• contact links
• certifications

Typical job description content includes:

• role title
• required skills
• preferred technologies
• domain expectations
• hiring signals and ATS-style keywords

Data quality considerations

The quality of system output depends heavily on:

• resume completeness
• document formatting quality
• text extraction quality for PDF/DOCX files
• clarity and relevance of the job description
• whether the resume contains quantified achievements or only generic statements

Privacy note

User resumes and reports can contain personal and sensitive career information. In production use, privacy, access control, retention policy, and deployment security should be treated as high-priority concerns.

---

Why ResumeLens Exists

Most resume feedback tools fail in one of two ways: they are either too generic to be useful, or they produce polished text without clearly explaining what is actually wrong with the original resume.

ResumeLens was created to solve a more practical problem:

How can we turn resume review into a structured, repeatable, AI-assisted workflow that gives both explanation and improvement?

The motivation behind ResumeLens includes:

• helping users tailor resumes to specific roles instead of relying on general advice
• showing users why they are a weak or strong fit, not just assigning a score
• identifying ATS keyword gaps in a transparent way
• converting vague resume weaknesses into concrete rewritten bullets and action items
• preserving historical results so improvement can be tracked over time
• demonstrating a realistic AI backend architecture with orchestration, persistence, and typed outputs

ResumeLens exists because most job seekers do not only need better wording. They need:

• stronger alignment to role requirements
• better visibility into missing skills
• more effective project and experience framing
• a structured way to improve over multiple iterations

Live Demo

https://youtu.be/7OtrqrkBK4s

GitHub repo

https://github.com/SimbaMunatsi/resume-lens

Methodology

ResumeLens uses a multi-stage AI workflow rather than a single prompt.

High-level methodology

1. Accept resume input as text or file
2. Optionally accept a job description as text or URL
3. Normalize and clean all textual inputs
4. Extract a structured candidate profile
5. Compare the profile against the target job
6. Generate a structured gap analysis
7. Produce rewritten bullets, ATS keywords, and action steps
8. Persist the results for later access and historical comparison

Design principles

• Separation of concerns: tools, agents, services, routes, and persistence are distinct
• Structured outputs: Pydantic schemas reduce ambiguity and stabilize downstream processing
• Deterministic + LLM hybrid logic: scoring and normalization are partially rule-based for more explainable behavior
• Persistence-first design: analysis history and user preferences make the system reusable over time
• Backend-first architecture: Streamlit consumes the API, but the backend remains the source of truth

Main analytical stages

• Resume extraction
• Job description acquisition
• Candidate profile generation
• Gap analysis and scoring
• Resume improvement generation
• Report assembly and persistence

System Architecture

ResumeLens is designed as a layered AI application.

Main layers

- Streamlit UI for user interaction
- FastAPI backend for validation, auth, orchestration, and API responses
- Tool layer for resume extraction, text cleaning, job fetching, and skill normalization
- Agent workflow for profile extraction, gap analysis, and improvement generation
- Service layer for assembling and persisting outputs
- PostgreSQL database for users, analyses, reports, and preferences

System Design

The 3-agent design

Agent 1: Resume Parsing & Profiling Agent

Responsibility

Convert raw resume text into a structured candidate profile.

Inputs
- raw resume text

Outputs
- candidate name
- email / links if present
- experience summary
- education
- skills
- projects
- certifications
- inferred seniority
- missing sections
- structured JSON profile

Why it exists

This agent creates the normalized state the rest of the workflow needs.

Agent 2: Job Match & Gap Analysis Agent

Responsibility

Compare the structured resume against the target job description.

Inputs
- candidate profile
- job description text

Outputs
- match score
- matched skills
- missing skills
- weak alignment areas
- high-priority gaps
- strengths relevant to the role
- ATS keyword gaps

Why it exists

This is the decision engine of the project.

Agent 3: Resume Improvement Agent

Responsibility

Turn analysis into practical resume improvements.

Inputs
- candidate profile
- job match report
- user preferences from memory

Outputs
- rewritten bullets
- missing keyword suggestions
- section-level recommendations
- final action plan
- tailored interview questions

Why it exists

This makes the system actually useful, not just analytical.

Tools

1. resume_extractor

Purpose: Extracts usable text from the resume input.
What it does:

• handles uploaded resume files
• supports formats like TXT, PDF, and DOCX
• converts file content into plain text for downstream analysis

Why it matters:

The rest of the pipeline cannot work on raw files. This tool is what turns a resume document into analysis-ready text.

2. job_fetcher

Purpose: Retrieves job description text from a public job URL.
What it does:

• sends a request to a provided job posting URL
• parses the page content
• extracts the relevant visible job description text
• raises a controlled error if fetching fails

Why it matters:

It allows the user to analyze their resume against a live job posting instead of manually copying the description.

3. text_cleaner

Purpose: Cleans and normalizes raw text before analysis.
What it does:

• removes unnecessary whitespace and formatting noise
• standardizes extracted resume text
• standardizes fetched or pasted job description text
• helps ensure empty or low-quality text is detected early

Why it matters:

Even good extraction can leave messy text behind. This tool improves consistency before the candidate profile and gap analysis stages.

4. skill_normalizer

Purpose: Standardizes skill names into a consistent format.
What it does:

• maps skill aliases to one canonical form
• examples:
  - Postgres → PostgreSQL
  - fast api → FastAPI
  - js → JavaScript

Why it matters:

Without normalization, the system may treat equivalent skills as different. This tool improves match accuracy during gap analysis and scoring.

Flow overview

Resume Input
-> Resume Extraction Tool
-> Text Cleaning
-> Candidate Profile Agent
-> Job Description Input / Job Fetch Tool
-> Gap Analysis Agent
-> Improvement Agent
-> Final Report Assembly
-> Save Analysis + Report + Preferences

Step-by-step explanation

1. Resume input
   The user either: pastes resume text or uploads a TXT, PDF, or DOCX file

2. Resume extraction
   The extraction layer converts uploaded documents into normalized text.

3. Text cleaning
   The text cleaner removes noise and standardizes formatting.

4. Candidate profile extraction
   The first agent converts the cleaned resume into a structured profile.

5. Job description acquisition
   The system either: uses pasted job description text or fetches and parses a public job URL

6. Gap analysis
   The second agent compares the candidate profile with job expectations, calculates match signals, and identifies missing or weak areas.

7. Improvement generation
   The third agent produces resume rewrites, ATS keyword guidance, role-fit feedback, interview questions, and an action plan.

8. Report assembly and storage
   The final response is returned to the user and persisted for history, review, and future comparison.

Code snippet

Below is a representative example of the analysis endpoint pattern used in ResumeLens. It shows validation, extraction, and structured response assembly:

@router.post("/run", response_model=ResumeExtractionResponse)
async def run_analysis(
    current_user: User = Depends(get_current_user),
    resume_file: UploadFile | None = File(default=None),
    resume_text: str | None = Form(default=None),
    job_description_text: str | None = Form(default=None),
    job_url: str | None = Form(default=None),
) -> ResumeExtractionResponse:
    if resume_file is None and not resume_text:
        raise HTTPException(status_code=400, detail="Provide either resume_file or resume_text.")

    if resume_file is not None and resume_text:
        raise HTTPException(status_code=400, detail="Provide only one of resume_file or resume_text.")

    if job_description_text and job_url:
        raise HTTPException(status_code=400, detail="Provide only one of job_description_text or job_url.")

    # Resume extraction and cleaning happen here
    # Job description fetch/cleaning happens here
    # Candidate profile, gap analysis, and final report generation follow

    return ResumeExtractionResponse(...)

This code reflects important engineering decisions:

• input validation at the API layer
• support for multiple input modes
• protected user workflow
• structured response modeling
• clean separation between endpoint logic and deeper analysis workflow

Getting Started

1. Clone the Repository

git clone https://github.com/SimbaMunatsi/resume-lens.git
cd resume-lens

2. Create and activate virtual environment

Windows

python -m venv venv
venv\Scripts\activate

Linux

python -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

Create a .env file and populate the required values.

Example:

APP_NAME=resume-lens
APP_VERSION=0.1.0
API_V1_PREFIX=/api/v1
DEBUG=True

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_SERVER=localhost
POSTGRES_PORT=5432
POSTGRES_DB=resume_lens

DATABASE_URL=postgresql://postgres:your_password@localhost:5432/resume_lens

LOG_LEVEL=INFO

SECRET_KEY=your secret key here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60

MAX_UPLOAD_SIZE_BYTES=2097152
ALLOWED_RESUME_EXTENSIONS=.pdf,.docx,.txt

JOB_FETCH_TIMEOUT_SECONDS=10
MAX_JOB_DESCRIPTION_CHARS=12000

OPENAI_API_KEY=your key here
OPENAI_MODEL=gpt-4.1-mini

5. Run database migration

alembic upgrade head

6. Start the FastAPI Backend

uvicorn app.main:app --reload

7. Start the Streamlit Frontend

streamlit run streamlit_app.py

Example resume + JD use case

Resume includes Python, FastAPI, PostgreSQL
Job requires Python, FastAPI, PostgreSQL, Docker
ResumeLens detects:

• strong backend alignment
• missing Docker evidence
• ATS keyword gap for Docker
• opportunities to strengthen project impact language

Observability and Monitoring

ResumeLens includes basic production-oriented observability patterns.

Current monitoring-related features

• structured request logging
• centralized exception handling
• explicit validation errors for malformed inputs
• controlled failure handling for job fetch failures
• graph / workflow stage visibility through modular services and agents
• analysis history persistence for traceability of past runs

Recommended future observability additions

• LangSmith tracing for agent and graph execution
• per-stage latency monitoring
• prompt + output trace inspection
• structured metrics for success/failure by tool and endpoint
• dashboarding for request volume, response times, and failure classes

Results

Main result categories

- structured candidate profile
- gap analysis score and findings
- rewritten resume bullets
- ATS keyword suggestions
- role-fit feedback
- interview questions
- action plan
- historical improvement comparison

ResumeLens produces outputs that are both diagnostic and actionable.

Practical value of results

The strongest result is not just the match score. It is the combination of:
- score
- explanation
- weaknesses
- rewritten output
- next steps

This makes the system useful for iterative resume improvement instead of one-time analysis.

Evaluation

ResumeLens currently relies on a combination of:
- unit tests
- integration tests
- deterministic validation logic
- schema-constrained outputs
- manual qualitative inspection of generated reports

Evaluation challenge

Because resume quality is partially subjective, evaluation must balance:
- structural correctness
- role alignment
- usefulness
- factuality
- actionability

##Limitations and Industry Insights

Limitations

1. Output quality depends on input quality
   Weak or incomplete resumes will limit profile accuracy and downstream recommendations.

2. Public job URL parsing is imperfect
   Some job sites have noisy HTML, dynamic rendering, or anti-scraping behavior.

3. Resume truthfulness is assumed
   The system can improve how a candidate presents experience, but it cannot verify whether claims are true.

4. Match scoring is useful but not absolute
   A resume score is a decision aid, not a hiring prediction model.

5. Industry/domain nuance is limited
   Specialized sectors may require stronger domain-aware heuristics or role-specific prompts.

6. LLM output variability still exists
   Even with structured schemas, some variation in phrasing and recommendation style is expected.

Industry Insights

• Recruiter-facing value often comes from clarity and alignment, not only from grammatical polishing.
• ATS optimization matters, but keyword stuffing without evidence is weak. Systems like ResumeLens work best when they encourage evidence-backed alignment.
• Candidates increasingly want role-specific feedback rather than generic resume advice.
• AI systems in career tooling are more useful when they combine:
  - structure
  - diagnostics
  - persistence
  - explainability

This is where ResumeLens is strongest.

Performance Characteristics and Requirements

Runtime characteristics

ResumeLens is designed for interactive local usage, not batch-scale processing.

Performance depends on:

• file size and quality of uploaded resume
• PDF/DOCX parsing speed
• network latency for public job URL fetching
• LLM response latency
• local machine resources
• database responsiveness

Typical resource requirements

For local development:

• Python virtual environment
• PostgreSQL instance
• internet access for external model/API calls
• moderate CPU and RAM for backend + Streamlit + database

Access and Availability

###Current availability
ResumeLens is currently designed for:

• local development
• portfolio demonstration
• technical publication and code review

Contact information

Creator: Victor Simbarashe Munatsi
Github
LinkedIn
vsmunatsi@gmail.com

License and Usage Rights

ResumeLens is released under the MIT License.