Metadata-Version: 2.4
Name: resume-roast
Version: 1.0.3
Summary: A terminal-based LLM-powered resume coaching tool
License-Expression: MIT
License-File: LICENSE
Author: Jeffery Fang
Author-email: jefferyfang324@gmail.com
Requires-Python: >=3.12
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: defusedxml (>=0.7.1,<1.0.0)
Requires-Dist: mammoth (>=1.11.0,<2.0.0)
Requires-Dist: openai (>=2.45.0,<3.0.0)
Requires-Dist: pymupdf4llm (>=1.28.0,<2.0.0)
Requires-Dist: rich (>=15.0.0,<16.0.0)
Requires-Dist: typer (>=0.16,<1.0)
Project-URL: Repository, https://github.com/jfang324/resume-roast
Description-Content-Type: text/markdown

[![PyPI Version](https://img.shields.io/pypi/v/resume-roast)](https://pypi.org/project/resume-roast/)
![Python Versions](https://img.shields.io/pypi/pyversions/resume-roast)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/resume-roast?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/resume-roast)
[![License](https://img.shields.io/github/license/jfang324/resume-roast)](https://github.com/jfang324/resume-roast/blob/main/LICENSE)
[![CI](https://github.com/jfang324/resume-roast/actions/workflows/ci.yaml/badge.svg)](https://github.com/jfang324/resume-roast/actions/workflows/ci.yaml)
[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)

# Resume Roast

A terminal-based LLM-powered resume coaching tool. Get brutal, structured feedback on your resume, refine individual bullet points through back-and-forth chat, or generate new resume blocks from scratch.

## Features

- **`evaluate`** — Submit a PDF or DOCX resume and receive a structured roast: per-category scores, highlighted strengths and weaknesses, and concrete rewrite suggestions with before/after examples
- **`interview`** — Agentic behavioral interview that asks resume-tailored questions, fact-checks answers against your resume, and scores them across ownership, technical competence, problem-solving, and collaboration
- **`refine`** — Interactive chat that coaches a single resume bullet, rating it on every turn and suggesting improvements
- **`generate-block`** — Chat-based interviewer that gathers details about a role or project, then generates a formatted resume block rated against our bullet-writing principles
- Multiple LLM models to choose from, with token usage and cost reporting — per reply in the chat sessions, per run for `evaluate` and `interview`
- Configurable persona (recruiter, hiring manager, senior engineer) and level (intern through senior) for evaluations

## Getting Started

### Prerequisites

- Python 3.12 or higher
- An NVIDIA NIM API key (get one at [build.nvidia.com](https://build.nvidia.com/))

### Installation

```sh
pip install resume-roast
```

For development:

```sh
git clone https://github.com/jfang324/resume-roast.git
cd resume-roast
poetry install
```

### First-Time Setup

Set your NVIDIA API key:

```sh
resume-roast config credentials
```

You can also configure the model, persona, seniority level, and the remaining settings:

```sh
resume-roast config settings
```

Configuration is stored in `~/.resume-roast/`.

## Usage

### Commands

| Command                       | Arguments & options                    | Description                                                            |
| ----------------------------- | -------------------------------------- | --------------------------------------------------------------------- |
| `evaluate <path>`             | `<path>` — PDF or DOCX resume          | Roast a resume: scores, strengths/weaknesses, and rewrite suggestions |
| `interview <path>`            | `<path>` — PDF or DOCX resume<br>`--report` — save a Markdown report to `~/.resume-roast/interview-reports/` | Run an agentic behavioral interview and score the answers |
| `refine <bullet>`             | `<bullet>` — the bullet text to coach  | Coach a single resume bullet through a back-and-forth chat             |
| `generate-block`              | *(none)*                               | Interview you about a role or project, then generate a resume block    |
| `config credentials`          | *(none)*                               | Set the API key for each provider                                     |
| `config settings`             | *(none)*                               | Choose each setting from its allowed values                           |
| `show credentials`            | *(none)*                               | Print saved API keys, masked                                          |
| `show settings`               | *(none)*                               | Print every setting's current value                                   |

`--debug` is a global option, so it goes before the command — `resume-roast --debug evaluate resume.pdf`. It writes full debug logs (including raw prompts and responses containing resume content) to `~/.resume-roast/logs/debug.log`.

### Evaluate a Resume

```sh
resume-roast evaluate path/to/resume.pdf
```

Extracts your resume, sends it to the LLM for structured analysis, and prints a diff-highlighted report with scores and rewrite suggestions.

### Refine a Bullet

```sh
resume-roast refine "Managed a team of 5 engineers"
```

Opens an interactive chat. The LLM coaches you, rating the bullet on every reply and suggesting improvements. Available commands:

| Command              | Action                                              |
| -------------------- | --------------------------------------------------- |
| `/replace <text>`    | Replace the bullet with a new version (re-rates it) |
| `/generate <notes>`  | Generate a candidate rewrite (notes optional)       |
| `/help`              | Show available commands                             |
| `/exit`              | End the session                                     |
| *(plain text)*       | Conversational coaching turn                        |

### Generate a Block

```sh
resume-roast generate-block
```

Opens an interactive chat. The LLM interviews you about a role or project, asking questions to gather specifics. Type `/generate` when you're ready to produce a formatted resume block (header + 3-6 bullet points). `/generate` always produces a block, rated 0-10 — if the details are thin it still generates, then names what would raise the score. Available commands:

| Command              | Action                                  |
| -------------------- | --------------------------------------- |
| `/generate <notes>`  | Generate a resume block (notes optional) |
| `/help`              | Show available commands                 |
| `/exit`              | End the session                         |
| *(plain text)*       | Answer questions, add details           |

### Interview

```sh
resume-roast interview path/to/resume.pdf
```

Starts an agentic behavioral interview. The LLM generates questions tailored to your resume, asks them one at a time, fact-checks your answers against the resume, and probes deeper with follow-ups when needed. After all questions, produces a competency report with per-category scores, strengths, and growth areas.

Pass `--report` to also save a detailed Markdown copy — verdict, per-question evidence, and fact-checks — under `~/.resume-roast/interview-reports/`. The file is named by timestamp and resume (e.g. `20260723-142530-resume.md`), so repeated runs accumulate without overwriting. Nothing is written if the interview ends before any answer is scored.

Available commands:

| Command        | Action                       |
| -------------- | ---------------------------- |
| `/exit`        | End the interview early      |

## Development

See [docs/development.md](docs/development.md) for setup and development commands.

## Tools & Technologies

### Core

- Python 3.12+
- Typer (CLI framework)
- Rich (terminal output, spinners, diff rendering)
- pymupdf4llm (PDF to Markdown extraction)
- mammoth (DOCX to Markdown extraction)
- defusedxml (safe XML parsing for DOCX metadata parts)
- openai SDK (NVIDIA NIM API client)

### Code Quality

- Ruff (linting + formatting)
- Pyright (strict type checking)
- Bandit (security linting)
- pre-commit hooks

### Testing

- pytest
- coverage (branch coverage, 85% minimum)
- pytest-asyncio

### Build & Package

- Poetry

## License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

