cv-tool
=======

A minimal CLI for generating targeted CVs and cover letters using OpenAI tool calling.

Requirements
------------
- Python 3.10+
- [OpenAI Python SDK](https://pypi.org/project/openai/)
- [`asciidoctor-pdf`](https://asciidoctor.org/docs/asciidoctor-pdf/)
- [python-dotenv](https://pypi.org/project/python-dotenv/)

Install
-------
Use pip to install the Python dependencies:

```
npm run pip
```

This installs the packages listed in `requirements.txt`. Ensure the
`asciidoctor-pdf` gem is available as well, for example with:

```
gem install --user-install asciidoctor-pdf
```

Usage
-----
```
python cvfit.py apply [options]
python cvfit.py render <file.adoc> [--output out.pdf] [--doc-output out.docx]
```

By default the command looks for `master.adoc`, `job_description.txt`, and any
`.adoc` or `.pdf` files placed in the `others/` directory. If the job
description file is missing you will be prompted to paste its content. The
model defaults to `gpt-5-nano` and `--max-steps` defaults to `5`. Successful runs
produce a timestamped AsciiDoc and PDF for the tailored CV and plain text plus
PDF for the cover letter under `output/adoc` and `output/pdf`.
Use `--jd-text` to supply the job description on the command line and `--language`
to switch the output language. Pass `-v` for verbose logs. The CLI reports
progress, runtime, and token usage. The `render` subcommand is helpful for
regenerating PDF and DOCX files after manually editing the generated AsciiDoc file.

To avoid repeated OpenAI calls, a unified master CV is cached across runs.
When the source documents are unchanged, the aggregator step is skipped.
The generated CV is also trimmed to roughly three pages to keep output
concise.

The `OPENAI_API_KEY` is read from the environment. You may place this
variable in a `.env` file in the project directory for convenience.

Web Interface
-------------
Install Python and web dependencies, then start both servers with npm:

```
pip install -r requirements.txt
npm install --no-package-lock
npm start
```

This opens the Angular app where you can paste a job description, review and edit the generated CV AsciiDoc and cover letter text, and preview or download the resulting PDFs.

Gmail Integration
-----------------
To enable Gmail features, create OAuth client credentials in the Google Cloud
Console and download the JSON file. The committed `server/gmail_credentials.json`
contains placeholder values only; point the `GMAIL_CLIENT_SECRETS` environment
variable at a private copy with real credentials and keep that file out of git.
Tokens produced by the OAuth flow should likewise live outside the repository.
Set `GMAIL_TOKEN_FILE` (defaults to `token.json`) to reference a location that
is not tracked and regenerate the credentials once the secrets have been rotated.

Selenium / Chrome Dependencies
------------------------------
The freelance.de and 9am fetchers rely on Selenium running a headless Chrome
browser. When the required system libraries are missing the application logs
errors such as "Chrome WebDriver is not available; cannot log into 9am" and no
pages are fetched. On Debian or Ubuntu systems install the libraries that the
Docker image now includes:

```
sudo apt-get install -y \
    ca-certificates fonts-liberation libasound2t64 libatk-bridge2.0-0 \
    libatk1.0-0 libdrm2 libgbm1 libgdk-pixbuf2.0-0 libgtk-3-0 libnss3 \
    libpango-1.0-0 libpangocairo-1.0-0 libxcomposite1 libxcursor1 \
    libxdamage1 libxi6 libxkbcommon0 libxrandr2 libxrender1 libxss1 libxtst6
```

With these packages installed Selenium Manager can download a compatible
Chrome build and the background Gmail sync is able to render fetched pages.

Keycloak Development Server
---------------------------

For local authentication during development a Keycloak server is provided. To
start it run:

```
cd keycloak
docker compose up
```

The server listens on [http://localhost:9080](http://localhost:9080) with the
default `admin` / `admin` credentials. The `realm-config` directory contains a
basic realm definition that is imported on startup. Update your `.env` file so
`KEYCLOAK_URL` points at this URL when using the development server. Include the
scheme (for example `http://`) or the application will default to `http://` when
one is not provided.

By default the application is configured to use the `cv-tool` realm hosted at
`https://auth.example.com`. If you have a different Keycloak instance, set
`KEYCLOAK_URL`, `KEYCLOAK_REALM`, and `KEYCLOAK_CLIENT_ID` in your environment
to match your server.