CV Formatter

A production-ready desktop application for Windows that ingests CVs (PDF/DOCX/Images), runs OCR when needed, parses structured data, and formats into DOCX according to user-selected layout templates.

Features

• Multi-format Support: Process PDF, DOCX, and image files (JPG, PNG, TIFF, BMP)
• Automatic OCR: Intelligent fallback to OCR for scanned PDFs and images
• Flexible Templates: YAML-based layout templates for customizable formatting
• Dual Interface: Both GUI and CLI for different use cases
• Exact Text Preservation: No paraphrasing, maintains original content
• Production Ready: Comprehensive error handling, logging, and packaging

Installation

Prerequisites

1. Python 3.12+ - Download from python.org
2. Tesseract OCR - Download from GitHub
   • Install to default location: C:\Program Files\Tesseract-OCR\
   • Or specify custom path in application settings

Install from Source

1. Clone the repository:

git clone https://github.com/cv-formatter/cv-formatter.git
cd cv-formatter

2. Create virtual environment:

python -m venv venv
venv\Scripts\activate

3. Install dependencies:

pip install -e .

Install Pre-built EXE

1. Download the latest release from Releases
2. Extract the ZIP file
3. Run CVFormatter.exe

Usage

GUI Application

Launch the GUI application:

python -m cv_formatter.app.gui

Or use the pre-built executable:

CVFormatter.exe

GUI Features:

• File picker for input CV
• Template selection dropdown
• Preview parsed data before generation
• Progress tracking and logging
• Settings dialog for Tesseract path and output directory

Command Line Interface

Process a single CV:

python -m cv_formatter.cli process -i "path/to/cv.pdf" -t "aldelia_default" -o "output.docx"

Preview parsed data:

python -m cv_formatter.cli process -i "path/to/cv.pdf" -t "aldelia_default" --preview

List available templates:

python -m cv_formatter.cli list-templates

Test OCR functionality:

python -m cv_formatter.cli test-ocr

Validate input file:

python -m cv_formatter.cli validate "path/to/cv.pdf"

CLI Options

• -i, --input: Input CV file (required)
• -t, --template: Template name (required)
• -o, --output: Output DOCX file path (optional)
• --tesseract: Path to Tesseract executable (optional)
• --force-ocr: Force OCR processing
• --preview: Preview parsed data without generating output
• -v, --verbose: Enable verbose logging

Templates

Creating Custom Templates

Templates are YAML files located in the templates/ directory. Here's the structure:

name: "My Custom Template"
description: "Description of the template"
base_template_docx: "templates/base/FinalTemplate.docx"

font:
  family: "Arial"
  size_pt: 11

spacing:
  h1_before: 12
  h1_after: 6
  sub_before: 6
  sub_after: 0
  between_subsections: 6
  before_next_h1: 12

bullets:
  style_name: "List Bullet"
  fallback_style: "List Bullet"
  indent_level_cm: 0.5

sections_order:
  - CAREER_SUMMARY
  - KEY_QUALIFICATIONS
  - WORK_EXPERIENCE
  - EDUCATION
  - CERTIFICATIONS

heading_styles:
  CAREER_SUMMARY: { case: "upper", level: 1, bold: true }
  KEY_QUALIFICATIONS: { case: "upper", level: 1, bold: true }
  WORK_EXPERIENCE: { case: "upper", level: 1, bold: true }

work_experience_block:
  format:
    - "DATE: [[DATE]]"
    - "COMPANY: [[COMPANY]]"
    - "POSITION: [[POSITION]]"
    - ""
    - "Duties:"
    - "[[DUTIES_BULLETS]]"
  rules:
    blank_lines_after_position: 2
    if_no_duties_blank_lines: 2

aliases:
  "Professional Certifications": "CERTIFICATIONS"
  "Skills & Competencies": "SKILLS"

strict_mode: true

Template Configuration

• font: Font family and size settings
• spacing: Spacing rules for headings and sections
• bullets: Bullet point styling
• sections_order: Order of sections in output
• heading_styles: Styling for section headings
• work_experience_block: Formatting for work experience entries
• aliases: Mapping of alternative section names
• strict_mode: Preserve exact text without paraphrasing

Supported File Types

Input Formats

• PDF: Text-based and scanned PDFs
• DOCX/DOC: Microsoft Word documents
• Images: JPG, JPEG, PNG, TIFF, BMP

Output Format

• DOCX: Microsoft Word format with custom formatting

Parsed Data Structure

The application extracts and structures CV data as follows:

{
  "meta": {
    "source_file": "path/to/cv.pdf",
    "parsed_at": "2023-01-01T12:00:00",
    "pipeline": ["pdfplumber", "ocr"]
  },
  "CAREER_SUMMARY": "Experienced software engineer...",
  "KEY_QUALIFICATIONS": ["5+ years experience", "Expert in Python"],
  "WORK_EXPERIENCE": [
    {
      "DATE": "2020 - Present",
      "COMPANY": "TechCorp Inc.",
      "POSITION": "Senior Software Engineer",
      "DUTIES": ["Led development...", "Implemented CI/CD..."]
    }
  ],
  "EDUCATION": ["2020 - BSc Computer Science - University X"],
  "CERTIFICATIONS": ["AWS Certified - 2022"],
  "SKILLS": ["Python", "JavaScript", "React"],
  "LANGUAGES": ["English - Fluent", "Spanish - Conversational"]
}

Development

Project Structure

cv-formatter/
├── src/cv_formatter/
│   ├── app/                 # GUI application
│   │   └── gui.py          # Main window and dialogs
│   ├── core/               # Core processing modules
│   │   ├── detect.py       # File type detection
│   │   ├── extract_*.py    # Text extraction modules
│   │   ├── ocr.py          # OCR processing
│   │   ├── parse.py        # CV parsing engine
│   │   ├── templates.py    # Template management
│   │   ├── format_docx.py  # DOCX formatting
│   │   ├── pipeline.py     # Main orchestrator
│   │   └── utils.py        # Utility functions
│   └── cli.py              # Command-line interface
├── templates/              # YAML template files
├── sample_inputs/          # Sample CV files for testing
├── tests/                  # Test suite
├── scripts/                # Build and utility scripts
└── assets/                 # Icons and resources

Running Tests

# Install test dependencies
pip install pytest pytest-cov

# Run tests
pytest tests/

# Run with coverage
pytest --cov=src/cv_formatter tests/

Building EXE

# Install PyInstaller
pip install pyinstaller

# Build executable
python scripts/build_exe.py

Or use the provided batch script:

scripts/build_exe.bat

Troubleshooting

Common Issues

1. Tesseract not found

   • Install Tesseract OCR from the official website
   • Set the correct path in application settings
   • Test OCR functionality using the CLI command

2. PDF text extraction fails

   • The application automatically falls back to OCR
   • Use --force-ocr flag to force OCR processing
   • Ensure PDF is not password-protected

3. Template not found

   • Check template file exists in templates/ directory
   • Validate YAML syntax
   • Use list-templates command to see available templates

4. Poor parsing results

   • Check CV format and section headings
   • Add custom aliases in template configuration
   • Use preview mode to verify parsed data

Log Files

The application creates log files in the current directory:

• cv_formatter.log - Main application log
• Logs are rotated when they reach 10MB

Getting Help

• Check the Issues page
• Review the Documentation
• Contact support at support@cvformatter.com

License

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Changelog

Version 1.0.0

• Initial release
• Support for PDF, DOCX, and image files
• OCR integration with Tesseract
• YAML-based template system
• GUI and CLI interfaces
• Comprehensive test suite
• PyInstaller packaging

Acknowledgments

• Tesseract OCR for OCR functionality
• python-docx for DOCX processing
• PySide6 for GUI framework
• Rich for CLI formatting