writeup-cv-cli 0.4.1

A command-line CV Analyzer tool that processes PDF resumes and performs analysis.

writeup - Software Engineering Project - 22916 2025A

A brief description of what this project does and who it's for

Authors

Contributor	GitHub Profile
@dolev146	GitHub
@shimshon21	GitHub
@yakov103	GitHub

Phase 1: Requirements Engineering

Consult with an LLM to define ONE significant and interesting CV analysis feature.

prompt : "I am a software developer developing a terminal Python app that gets a CV (curriculum vitae) PDF file as input and a text prompt from the user, for example, "Does this CV match the iOS developer?" I want to consult with you about what could be a significant and interesting analysis feature I can implement in my software. Document the feature's requirements clearly. Include acceptance criteria. The users of our software will be Human resources trying to find the best job applicant."

Document the feature's requirements clearly (inline).

Feature Overview Feature Name Role Matching & Competency Analysis

Description The Role Matching & Competency Analysis feature takes a PDF CV and a text prompt describing the job role (e.g., “iOS Developer” or specific requirement job post. It then analyzes the CV content for skills, experiences, and qualifications relevant to that role. The outcome is a numerical score, a list of matched competencies/keywords, and a brief explanation of why the CV might or might not be suitable.

User Stories

As an HR professional, I want to input a CV and a prompt describing the job position so that I can receive a quick assessment of how well the CV matches the role. As an HR professional, I want to see a breakdown of relevant skills and experiences extracted from the CV so that I can understand the candidate's strengths and areas where they might fall short. As an HR professional, I want a confidence or match score that summarizes the overall fit so that I can compare multiple applicants easily.

Functional Requirements

1. File Parsing & Text Extraction Accept PDF input via command line, extract text reliably (up to ~10 pages).

2. Keyword & Competency Extraction Identify relevant skills using a predefined list or NLP; optionally highlight them in output.

3. Scoring Mechanism Generate a 0-100 score based on keyword frequency, critical experience, and years of experience.

Non-Functional Requirements

1. Reliability The system should reliably parse PDFs with standard text. If the PDF is scanned or image-based, the system may return an error or a warning unless Optical Character Recognition (OCR) is implemented.

Include acceptance criteria (inline)

Acceptance Criteria CV Input & Prompt Capture

Given a valid PDF file path and a relevant prompt, when the user runs the software in the terminal, then the software extracts text from the PDF and processes the prompt without error.

Analysis & Scoring

Given a valid PDF that includes skills relevant to the prompt (e.g., iOS development skills) and a prompt “Does this CV match iOS developer?”, when the user runs the analysis, then the system outputs: A match score between 0 and 100, A list of detected relevant skills (e.g., “Swift,” “Objective-C,” “UIKit”), A short textual summary describing the candidate’s suitability. No Relevant Skills Found

Given a valid PDF that lacks any relevant skills for the prompt, when the user runs the analysis, then the system outputs a low match score (e.g., near 0) and indicates no relevant skills found. Invalid CV or Prompt

Given an invalid or non-existent PDF file path, when the user runs the software, then the system provides an error message and does not crash. Given an empty or nonsensical prompt (e.g., “asdfghjk”), when the user runs the software, then the system warns the user that the role could not be identified and proceeds with minimal or no matching. Performance

Given a CV of ~5 pages, when the user runs the analysis, then the system should return results within a few seconds (e.g., under 5 seconds).

• Document LLM interactions (link). chat

Phase 2: Architecture

Define command-line interface specification (inline).

Cli commends: writeup evaluate --help

Description: Provide additional information of the command 'scan' as described below

writeup evaluate <RESUME_PATH> <JOB_DESCRIPTION_PATH> [OPTIONS]

Description: Scans the resume located at RESUME_PATH against the job description in JOB_DESCRIPTION_PATH and returns a match score, highlight relevant skills and also provide a short summary.

Arguments

<RESUME_PATH> – A path or filename for the resume (PDF format).

<JOB_DESCRIPTION_PATH> – A path or filename for the job description (usually a TXT file). Options:

--api-key TEXT Required API key used for accessing the Gemini or other LLM-based API. Example: --api-key "YOUR_API_KEY_HERE"

--output, -o TEXT Path to an optional output file (e.g., JSON) for storing the results. Example: --output "results.json"

Examples

Basic usage with console output only

writeup scan my_resume.pdf job_description.txt --api-key "123abc"

Saving results to a JSON file

writeup scan my_resume.pdf job_description.txt --api-key "123abc" -o output/results.json

Plan file system interactions, i.e., input/output (inline).

Inputs

Resume: A PDF file. The CLI will accept a file path (resume_path) and parse or extract text from the resume. Job Description: Provided as a plain text or similar file (job_description_path).

Outputs: Displays the final “match score” and a short text-based summary. Optional JSON file: If --output is specified, the CLI writes a JSON with fields such as: json Copy Edit

{
   class Feedback(BaseModel):
      score: float
      summary: str
      skills: list[str]
}

Your feature may use additional files for input and output.

A .env file or config file could store default API_KEY and other environment variables.

A logs directory could store logs if needed for debugging or usage reporting.

Identify relevant third-party libraries (inline).

Typer

For easy and intuitive CLI creation.

Poetry

Dependency management and project packaging.

Curl

For requests

pydantic(To check)

For data validation and structured output if needed.

Define team member responsibilities (inline).

TODO

LLM Interactions: chat

Phase 3: Design

CRC: Classes, Responsibilities, and Collaborations

CLIHandler (or WriteupCLI)

Responsibility:

Parse command-line arguments (resume path, job description path, API key, output file). Orchestrate the overall flow: call parser, analyzer, and output results.

Collaborations:

Uses Parser to extract text from files. Uses Analyzer to get the match score and summary. Writes results to console and/or calls a helper to save results to a file.

Analyzer

Responsibility:

Accept two chunks of text (resume text, job description text). Possibly preprocess or clean text (removing extra whitespace, tokenizing, etc.). Work with the GeminiClient (or local logic) to compute a match score and a concise summary.

Collaborations:

Delegates actual similarity computation or LLM-based analysis to GeminiClient. Returns the final score and summary to the CLIHandler for output.

GeminiClient (or LLMClient)

Responsibility:

Wrap all calls to the external Gemini API. Handle authentication (API keys), network requests, error handling, and response parsing.

Collaborations: Called by Analyzer to generate a similarity score and short text summary (if using an API-based approach). Returns data back to Analyzer.

OutputManager (optional):

If the project grows in complexity, a dedicated class or function may handle JSON/CSV output formatting, logging, etc. Currently, the CLIHandler can handle basic output tasks directly.

Phase 4: Coding & Testing

Phase 5: Documentation

Demo

Insert gif or link to demo

Installation

1. Clone the repository:

   git clone <repository_url>
   cd writeup
   

2. Install dependencies with Poetry:

   poetry install
   

3. Activate the virtual environment:

   poetry shell
   

Usage

After installing, you can run the CLI command as follows:

writeup scan --pdf-path path/to/cv.pdf

This command scans and analyzes the provided CV PDF file and outputs an analysis report.

Development

• Run Tests:

  poetry run pytest
  

• LLM Interactions: Save all LLM chats in the chats/ directory.

Screenshots

Acknowledgements

• Awesome Readme Templates
• Awesome README
• How to write a Good readme