hr-breaker - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #llm #golang #go #android #machine-learning #macos #java #windows #cli #vue #security #openai

hr-breaker

(★ 858)

Optimize resume for jobs, now with AI

File Explorer

Download Latest Version (.zip)

- - claude-review.yml
  - tests.yml
- - fix-non-ascii-resume-upload.md
- repro_vision_bug.py
- - __init__.py
  - cli.py
  - config.py
  - litellm_patch.py
  - orchestration.py
  - server.py
- resume.html
- resume_guide.md
- resume_wrapper.html
- __init__.py
- conftest.py
- test_agent_construction.py
- test_api_key_sanitizer.py
- test_cache.py
- test_cli.py
- test_combined_reviewer.py
- test_config_logging.py
- test_config_override.py
- test_data_validator.py
- test_extraction_worker.py
- test_extractor.py
- test_filter_language.py
- test_filters.py
- test_job_scraper.py
- test_litellm_patch.py
- test_llm_providers.py
- test_models.py
- test_optimization_telemetry.py
- test_optimizer_language.py
- test_orchestration.py
- test_orchestration_logging.py
- test_pdf_parser.py
- test_pdf_storage.py
- test_profile_retrieval.py
- test_profile_store.py
- test_profile_synthesis.py
- test_renderer.py
- test_retry.py
- test_server.py
- test_server_settings.py
- test_translation.py
- test_translation_checker.py
- test_utils.py
.env.example
.gitignore
.python-version
CLAUDE.md
LICENSE
pyproject.toml
README.md
uv.lock

# Installation Guide

1. Get the code

git clone https://github.com/btseytlin/hr-breaker

Downloads the entire project code from GitHub to your computer.

cd hr-breaker

Moves into the project folder you just downloaded.

2. Python

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

pip install .

Installs the package published on PyPI directly — no need to clone the source.

python <실행할 파일명>.py # README에서 정확한 실행 파일명을 확인하세요

Runs the Python script (or module).

✅ If it runs without errors and prints output in the terminal, it worked.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# HR-Breaker

Resume optimization tool that transforms any resume into a job-specific, ATS-friendly PDF.

![Python 3.10–3.13](https://img.shields.io/badge/python-3.10--3.13-blue.svg)

## Features

- **Any format in** - LaTeX, plain text, markdown, HTML, PDF
- **Optimized PDF out** - Single-page, professionally formatted
- **LLM-powered optimization** - Tailors content to job requirements
- **Minimal changes** - Preserves your content, only restructures for fit
- **No fabrication** - Hallucination detection prevents made-up claims
- **Opinionated formatting** - Follows proven resume guidelines (one page, no fluff, etc.)
- **Multi-filter validation** - ATS simulation, keyword matching, structure checks
- **Profile system** - Group multiple resume documents into profiles with LLM-powered extraction and synthesis
- **User instructions** - Guide the optimizer with extra context ("Focus on Python", "Add K8s cert")
- **Multi-language output** - Auto-detect language from job/resume, or force a specific language (e.g. `-l ru`)
- **Web UI + CLI** - FastAPI + Alpine.js web app or command-line
- **Debug mode** - Inspect optimization iterations
- **Cross-platform** - Works on macOS, Linux, and Windows

## How It Works

1. Upload resume in any text format (content source only)
2. Provide job posting URL or text description
3. LLM extracts content and generates optimized HTML resume
4. System runs internal filters (ATS simulation, keyword matching, hallucination detection)
5. If filters reject, regenerates using feedback
6. When all checks pass, renders HTML→PDF via WeasyPrint

## Quick Start

```bash
# Install
uv sync

# Configure
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY (or configure another LLM provider)

# Run web UI (auto-opens browser at http://localhost:8899)
uv run hr-breaker serve
```

## Usage

### Web UI

Launch with `uv run hr-breaker serve` (default: http://localhost:8899)

1. Drop a file or paste text to create a resume profile (or click an existing one)
2. Enter job URL or paste description
3. Configure settings in sidebar (models, API keys, filter thresholds)
4. Click optimize — real-time progress via SSE
5. Preview and download PDF

Profiles group your resume documents — drop a file to auto-create a profile, or create one manually and add multiple documents. Click a profile to synthesize it into a resume, or click the edit icon to manage documents.

### CLI

```bash
# From URL
uv run hr-breaker optimize resume.txt https://example.com/job

# From job description file
uv run hr-breaker optimize resume.txt job.txt

# Debug mode (saves iterations) — on by default, -D to disable
uv run hr-breaker optimize resume.txt job.txt -D

# User instructions - guide the optimizer
uv run hr-breaker optimize resume.txt job.txt -i "Focus on Python, add K8s cert"

# Language modes: from_job (default), from_resume, en, ru, etc.
uv run hr-breaker optimize resume.txt https://example.com/job -l ru
uv run hr-breaker optimize resume.txt https://example.com/job -l from_job

# Lenient mode - relaxes content constraints but still prevents fabricating experience. Use with caution!
uv run hr-breaker optimize resume.txt job.txt --no-shame

# List generated PDFs
uv run hr-breaker list
```

## Output

- Final PDFs: `output/<MMDD_HHMM>_<name>_<company>_<role>_<lang>.pdf`
- Debug iterations: `output/<MMDD_HHMM>_debug_<company>_<role>/`
- Records: `output/index.json`

## Configuration

Copy `.env.example` to `.env` and set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`). Models are configurable via LiteLLM — any provider (OpenAI, Anthropic, Moonshot, etc.) works by setting `PRO_MODEL`, `FLASH_MODEL`, and the corresponding API key. To cap expensive responses, you can also set `MAX_TOKENS` (or the alias `MAX_OUTPUT_TOKENS`). See `.env.example` for all options.

---

## Architecture

```
src/hr_breaker/
├── agents/          # Pydantic-AI agents (optimizer, reviewer, etc.)
├── filters/         # Validation plugins (ATS, keywords, hallucination)
├── services/        # Rendering, scraping, caching, profiles
│   └── scrapers/    # Job scraper implementations
├── models/          # Pydantic data models
├── static/          # Frontend (Alpine.js + CSS + JS)
├── orchestration.py # Core optimization loop
├── server.py        # FastAPI app (API + SSE streaming)
└── cli.py           # Click CLI
```

**Filters** (run by priority):

- 0: ContentLengthChecker - Size check
- 1: DataValidator - HTML structure validation
- 3: HallucinationChecker - Detect fabricated claims not supported by original resume
- 4: KeywordMatcher - TF-IDF matching
- 5: LLMChecker - Visual formatting check and LLM-based ATS simulation
- 6: VectorSimilarityMatcher - Semantic similarity
- 7: AIGeneratedChecker - Detect AI-sounding text
- 8: TranslationQualityChecker - Translation quality (skipped when source == target language)

## Development

```bash
# Run tests
uv run pytest tests/

# Install dev dependencies
uv sync --group dev
```