simple-resume 0.3.2

Generate PDF resumes from YAML data using HTML templates

Generate polished PDF and HTML resumes from a single YAML file.

simple-resume

A Python 3.10+ CLI and library for converting structured YAML (or JSON Resume) into PDF, HTML, or LaTeX. Templates and static assets ship with the package so you can render without creating additional content.

Why Simple-Resume

• Keep your resume version-controlled as plain YAML.
• Swap templates, palettes, and formats without rewriting content.
• Score resumes against job descriptions with built-in ATS algorithms.
• Pure-Python core with shell adapters; effects are testable and side-effect aware.
• Bundled HTML templates and static assets prevent "TemplateNotFound" errors in wheels and editable installs.

Feature Comparison

Feature	simple-resume	JSON Resume	HackMyResume	Resume.io
Open Source	Yes	Yes	Yes	No
Data Format	YAML + JSON Resume	JSON	JSON/FRESH	Proprietary
Version Control	Git-friendly	Git-friendly	Git-friendly	Cloud-only
Local Processing	100% private	100% private	100% private	Cloud storage
Template System	HTML + Jinja2	JSON themes	Multiple formats	Web builder
LaTeX Support	Yes	No	No	No
Python API	Native	No	No	No
CLI Tools	Yes	Yes	Yes	No
Real-time Preview	HTML + auto-reload	No	No	Yes
ATS Scoring	Built-in (4 algorithms)	No	No	No
Custom Themes	Unlimited	Limited	Limited	Paid only
Color Palettes	Yes	No	Basic	Limited

See Detailed Comparison for full analysis.

Installation

# With uv (recommended)
uv add simple-resume

# With pip
pip install simple-resume

Platform requirements: Python 3.10+ on Linux, macOS, or Windows. PDF output uses WeasyPrint, which requires Cairo/Pango/GTK system libraries (see Usage Guide).

Quick Start

Create a YAML file in resume_private/input/my_resume.yaml:

JSON Resume (*.json from jsonresume.org) is also supported — drop it into your input/ folder and simple-resume auto-converts it at load time.

Editor autocomplete is available via the JSON Schema at src/simple_resume/shell/assets/static/schema.json.

template: resume_no_bars
full_name: Jane Doe
email: [e-mail]
body:
  Experience:
    - title: Senior Engineer
      company: TechCorp
      start: 2022
      end: Present
      description: |
        - Lead microservices migration
        - Improved latency by 40%

Generate output:

uv run simple-resume generate --format pdf         # PDF
uv run simple-resume generate --format html --open # HTML + browser

Built-in templates: resume_no_bars, resume_with_bars, resume_modern, resume_professional, resume_creative, demo. Cover letters use the cover template. See src/simple_resume/shell/assets/templates/html/ for all templates.

Python API

from simple_resume import generate, preview

results = generate("resume_private/input/my_resume.yaml",
                   formats=["pdf", "html"])
print(results["pdf"].output_path)

# Browser preview with live reload
preview("resume_private/input/my_resume.yaml")

For batch operations:

from simple_resume import ResumeSession

with ResumeSession(data_dir="resume_private") as session:
    session.generate_all(format="pdf")

See API Reference and API Stability Policy for the full public surface.

ATS Resume Scoring

Score resumes against job descriptions using multiple NLP algorithms.

CLI

# Single resume
uv run simple-resume screen resume.yaml job.txt

# Score a PDF or HTML resume directly
uv run simple-resume screen resume.pdf job.txt

# Human reviewer mode (emphasizes semantic similarity)
uv run simple-resume screen resume.yaml job.txt --mode human

# Batch mode — rank all resumes in a directory
uv run simple-resume screen resumes/ job.txt --batch --top 5

# Batch with structured output and detail
uv run simple-resume screen resumes/ job.txt --batch --format json --verbose

Supported input formats: .yaml, .yml, .json, .txt, .md, .pdf, .html, .htm.

Python API

from simple_resume import score_resume

result = score_resume(
    resume_text="Senior Python Developer with 5 years experience...",
    job_description="Looking for a Senior Python Engineer..."
)
print(f"Match score: {result.overall_score * 100:.1f}%")

Scoring algorithms

• TF-IDF + Cosine Similarity — statistical term frequency analysis
• Jaccard + N-gram — set intersection and phrase overlap
• Exact Keyword — direct matching with fuzzy tolerance and skills taxonomy (800+ skills from O*NET and LinkedIn bundles)
• BERT Semantic — contextual embeddings via sentence-transformers (optional: uv add simple-resume[bert])

The tournament system combines algorithms using weighted averages with mode-specific presets (--mode ats or --mode human). See ATS API Reference for the scoring API, ATS Scoring Rubric for methodology, and Similarity Algorithm Evaluation for benchmarks.

Customization

• Palettes: --palette "Professional Blue" or --palette path/to/palette.yaml
• Custom templates: --template custom.html with --templates-dir /path/to/templates
• LaTeX: set config.output_mode: latex and compile with your TeX toolchain (see Usage Guide)
• Color utilities: simple_resume.core.colors.get_contrasting_text_color for accessibility checks

Documentation

Getting started: Getting Started, Usage Guide, Workflows, Path Handling

API: API Reference, ATS API Reference, Shell Layer APIs, API Stability Policy

Architecture: Architecture Guide, Lazy Loading, Migration Guide

Design: Color Schemes, PDF Renderer Evaluation

Samples: sample/ directory

Development

git clone https://github.com/athola/simple-resume.git
cd simple-resume
uv sync --dev --extra utils   # or: pip install -e .[dev,utils]

Run checks before opening a PR:

make lint && make test         # or: make check-all validate

Releases are automated via GitHub Actions — tag with v* and push:

git tag v0.1.2 && git push origin v0.1.2

See Development Guide and Contributing for full details. Submit issues or ideas in GitHub Issues.

Troubleshooting

• TemplateNotFound: confirm installation includes packaged assets; custom templates require --templates-dir.
• PDF on Linux: install system libs cairo, pango, gdk-pixbuf (WeasyPrint requirement).
• PDF rendering errors: simple-resume pins pydyf>=0.10.0,<0.12.0 to avoid incompatible releases. Overriding this constraint may cause silent failures.
• Case-variant input/ directories: Input/, INPUT/, etc. are detected automatically (v0.2.5+).

License

MIT License. See LICENSE.

Star History